home *** CD-ROM | disk | FTP | other *** search
\chapter{Built-In Predicates} \section{Notation of Predicate Descriptions} We have tried to keep the predicate descriptions clear and concise. First the predicate name is printed in bold face, followed by the arguments in italics. Arguments are preceded by a `+', `-' or `?' sign. `+' indicates the argument is input to the predicate, `-' denotes output and `?' denotes `either input or output'.% \footnote{These marks do \strong{notx} suggest instantiation (e.g.\ var(+Var)).} Constructs like `op/3' refer to the predicate `op' with arity `3'. \section{Consulting Prolog Source files} \label{sec:consulting} SWI-Prolog source files normally have a suffix `\fileext{pl}'. Specifying the suffix is optional. All predicates that handle source files first check whether a file with suffix `\fileext{pl}' exists. If not the plain file name is checked for existence. Library files are specified by embedding the file name using the functor \functor{library}{1}. Thus `\file{foo}' refers to `\file{foo.pl}' or `\file{foo}' in the current directory, `\file{library(foo)}' refers to `\file{foo.pl}' or `\file{foo}' in one of the library directories specified by the dynamic predicate library_directory/1. The user may specify other `aliases' than \file{library} using the predicate file_search_path/2. This is strongly encouraged for managing complex applications. See also absolute_file_name/[2,3]. SWI-Prolog recognises grammar rules as defined in \cite{Clocksin:87}. The user may define additional compilation of the source file by defining the dynamic predicate term_expansion/2. Transformations by this predicate overrule the systems grammar rule transformations. It is not allowed to use assert/1, retract/1 or any other database predicate in term_expansion/2 other than for local computational purposes.% \footnote{ It does work for consult, but makes it impossible to compile programs into a stand alone executable (see \secref{compilation})} Directives may be placed anywhere in a source file, invoking any predicate. They are executed when encountered. If the directive fails, a warning is printed. Directives are specified by :-/1 or ?-/1. There is no difference between the two. SWI-Prolog does not have a separate reconsult/1 predicate. Reconsulting is implied automatically by the fact that a file is consulted which is already loaded. \begin{description} \predicate{load_files}{2}{+Files, +Options} The predicate load_files/2 is the parent of all the other loading predicates. It currently supports a subset of the options of Quintus load_files/2. \arg{Files} is either specifies a single, or a list of source-files. The specification for a source-file is handled absolute_file_name/2. See this predicate for the supported expansions. \arg{Options} is a list of options using the format \begin{quote} \arg{OptionName}(\arg{OptionValue}) \end{quote} The following options are currently supported: \begin{description} \termitem{if}{Condition} Load the file only if the specified condition is satisfied. The value \const{true} loads the file unconditionally, \const{changed} loads the file if it was not loaded before, or has been modified since it was loaded the last time, \const{not_loaded} loads the file if it was not loaded before. \termitem{must_be_module}{Bool} If \const{true}, raise an error if the file is not a module file. Used by use_module/[1,2]. \termitem{imports}{ListOrAll} If \const{all} and the file is a module file, import all public predicates. Otherwise import only the named predicates. Each predicate is refered to as <name>/<arity>. This option has no effect if the file is not a module file. \termitem{silent}{Bool} If \const{true}, load the file without printing a message. The specified value is the default for all files loaded as a result of loading the specified files. \end{description} \predicate{consult}{1}{+File} Read \arg{File} as a Prolog source file. \arg{File} may be a list of files, in which case all members are consulted in turn. \arg{File} may start with the csh(1) special sequences \file{~}, \file{~<user>} and \file{$<var>}. \arg{File} may also be \file{library(Name)}, in which case the libraries are searched for a file with the specified name. See also library_directory/1 and file_search_path/2. consult/1 may be abbreviated by just typing a number of file names in a list. Examples: \begin{center}\begin{tabular}{ll} \exam{?- consult(load).} & \% consult \file{load} or \file{load.pl} \\ \exam{?- [library(quintus)]}. & \% load Quintus compatibility library \\ \end{tabular}\end{center} Equivalent to load_files(Files, []). \predicate{ensure_loaded}{1}{+File} If the file is not already loaded, this is equivalent to consult/1. Otherwise, if the file defines a module, import all public predicates. Finally, if the file is already loaded, is not a module file and the context module is not the global user module, ensure_loaded/1 will call consult/1. With the semantics, we hope to get as closely possible to the clear semantics without the presence of a module system. Applications using modules should consider using use_module/[1,2]. Equivalent to load_files(Files, [if(changed)]). \predicate{require}{1}{+ListOfNameAndArity} Declare that this file/module requires the specified predicates to be defined ``with their commonly accepted definition''. This predicate originates from the Prolog portability layer for XPCE. It is intended to provide a portable mechanism for specifying that this module requires the specified predicates. The implementation normally first verifies whether the predicate is already defined. If not, it will search the libraries and load the required library. SWI-Prolog, having autoloading, does {\bf not} load the library. Instead it creates a procedure header for the predicate if this does not exist. This will flag the predicate as `undefined'. See also check/0 and autoload/0. \predicate{make}{0}{} Consult all source files that have been changed since they were consulted. It checks \arg{all} loaded source files: files loaded into a compiled state using \exam{pl -c \ldots} and files loaded using consult or one of its derivatives. make/0 is normally invoked by the edit/[0,1] and ed/[0,1] predicates. make/0 can be combined with the compiler to speed up the development of large packages. In this case compile the package using \begin{code} sun% pl -g make -o my_program -c file ... \end{code} If `my_program' is started it will first reconsult all source files that have changed since the compilation. \predicate{library_directory}{1}{?Atom} Dynamic predicate used to specify library directories. Default \file{./lib}, \file{~/lib/prolog} and the system's library (in this order) are defined. The user may add library directories using assert/1, asserta/1 or remove system defaults using retract/1. \predicate{file_search_path}{2}{+Alias, ?Path} Dynamic predicate used to specify `path-aliases'. This feature is best described using an example. Given the definition \begin{code} file_search_path(demo, '~/demo'). \end{code} the file specification \file{demo(myfile)} will be expanded to \file{~/demo/myfile}. The second argument of file_search_path/2 may be another alias. Below is the initial definition of the file search path. This path implies \file{swi(<Path>)} refers to a file in the SWI-Prolog home directory. The alias \file{foreign(<Path>)} is intended for storing shared libraries (\fileext{so} or \fileext{DLL} files). See also load_foreign_library/[1,2]. \begin{code} user:file_search_path(library, X) :- library_directory(X). user:file_search_path(swi, Home) :- feature(home, Home). user:file_search_path(foreign, swi(ArchLib)) :- feature(arch, Arch), concat('lib/', Arch, ArchLib). user:file_search_path(foreign, swi(lib)). \end{code} The file_search_path/2 expansion is used by all loading predicates as well as by absolute_file_name/2. \predicate{expand_file_search_path}{2}{+Spec, -Path} Unifies \arg{Path} will all possible expansions of the file name specification \arg{Spec}. See also absolute_file_name/3. \predicate{source_file}{1}{?File} Succeeds if \arg{File} was loaded using consult/1 or ensure_loaded/1. \arg{File} refers to the full path name of the file (see expand_file_name/2). The predicate source_file/1 backtracks over all loaded source files. \predicate{source_file}{2}{?Pred, ?File} Is true if the predicate specified by \arg{Pred} was loaded from file \arg{File}, where \arg{File} is an absolute path name (see expand_file_name/2). Can be used with any instantiation pattern, but the database only maintains the source file for each predicate. Predicates declared \const{multifile} (see multifile/1) cannot be found this way. \predicate{prolog_load_context}{2}{?Key, ?Value} Determine loading context. The following keys are defined: \begin{center} \begin{tabular}{|l|p{4in}|} \hline \bf Key & \bf Description \\ \hline \const{module} & Module into which file is loaded \\ \const{file} & File loaded \\ \const{stream} & Stream identifier (see current_input/1) \\ \const{directory} & Directory in which \arg{File} lives. \\ \const{term_position} & Position of last term read. Term of the form \mbox{\tt '\$stream_position'(0,<Line>,0,0,0)} \\ \hline \end{tabular} \end{center} Quintus compatibility predicate. See also source_location/2. \predicate{source_location}{2}{-File, -Line} If the last term has been read from a physical file (i.e.\ not from the file \const{user} or a string), unify \arg{File} with an absolute path to the file and \arg{Line} with the line-number in the file. New code should use prolog_load_context/2. \predicate{term_expansion}{2}{+Term1, -Term2} Dynamic predicate, normally not defined. When defined by the user all terms read during consulting that are given to this predicate. If the predicate succeeds Prolog will assert \arg{Term2} in the database rather then the read term (\arg{Term1}). \arg{Term2} may be a term of a the form `?- \arg{Goal}' or `:- \arg{Goal}'. \arg{Goal} is then treated as a directive. If \arg{Term2} is a list all terms of the list are stored in the database or called (for directives). If \arg{Term2} is of the form below, the system will assert \arg{Clause} and record the indicated source-location with it. \begin{quote} \mbox{\tt '\$source_location'(<File>, <Line>):<Clause>} \end{quote} When compiling a module (see \chapref{modules} and the directive module/2), expand_term/2 will first try term_expansion/2 in the module being compiled to allow for term-expansion rules that are local to a module. If there is no local definition, or the local definition fails to translate the term, expand_term/2 will try user:term_expansion/2. For compatibility with SICStus and Quintus Prolog, this feature should not be used. See also expand_term/2. \predicate{expand_term}{2}{+Term1, -Term2} This predicate is normally called by the compiler to perform preprocessing. First it calls term_expansion/2. If this predicate fails it performs a grammar-rule translation. If this fails it returns the first argument. \predicate{at_initialization}{1}{+Goal} Register \arg{Goal} to be ran when the system initialises. Initialisation takes place after reloading a .qlf (formerly .wic) file as well as after reloading a saved-state. The hooks are run in the order they were registered. A warning message is issued if \arg{Goal} fails, but execution continues. See also at_halt/1 \predicate{at_halt}{1}{+Goal} Register \arg{Goal} to be ran when the system halts. The hooks are run in the order they were registered. Success or failure executing a hook is ignored. These hooks may not call halt/[0,1]. \predicate{initialization}{1}{+Goal} Call \arg{Goal} and register it using at_initialization/1. Directives that do other things that creating clauses, records, flags or setting predicate attributes should normally be written using this tag to ensure the initialisation is executed when a saved system starts. See also qsave_program/[1,2]. \predicate{compiling}{0}{} Succeeds if the system is compiling source files with the \cmdlineoption{-c} option into an intermediate code file. Can be used to perform code optimisations in expand_term/2 under this condition. \predicate{preprocessor}{2}{-Old, +New} Read the input file via a Unix process that acts as preprocessor. A preprocessor is specified as an atom. The first occurrence of the string `\const{\%f}' is replaced by the name of the file to be loaded. The resulting atom is called as a Unix command and the standard output of this command is loaded. To use the Unix C preprocessor one should define: \begin{code} ?- preprocessor(Old, '/lib/cpp -C -P %f'), consult(...). Old = none \end{code} \end{description} \subsection{Quick Load Files} The features described in this section should be regarded {\bf alpha}. As of version 2.0.0, SWI-Prolog supports compilation of individual or multiple Prolog sourcefiles into `Quick Load Files'. A `Quick Load Files' (\fileext{qlf} file) stores the contents of the file in a precompiled format very similar to compiled files created using the \cmdlineoption{-b} and \cmdlineoption{-c} flags (see \secref{compilation}). These files load considerably faster than sourcefiles and are normally more compact. They are machine independent and may thus be loaded on any implementation of SWI-Prolog. Note however that clauses are stored as virtual machine instructions. Changes to the compiler will generally make old compiled files unusable. Quick Load Files are created using qcompile/1. They may be loaded explicitly using qload/1 or implicitly using consult/1 or one of the other file-loading predicates described in \secref{consulting}. If consult is given the explicit \fileext{pl} file, it will load the Prolog source. When given the \fileext{qlf} file, it will call qload/1 to load the file. When no extension is specified, it will load the \fileext{qlf} file when present and the fileext{pl} file otherwise. \begin{description} \predicate{qcompile}{1}{+File} Takes a single file specification like consult/1 (i.e. accepts constructs like \file{library(LibFile)} and creates a Quick Load File from \arg{File}. The file-extension of this file is \fileext{qlf}. The base name of the Quick Load File is the same as the input file. If the file contains `\exam{:- consult(\arg{+File})}' or `\exam{:- [\arg{+File}]}' statements, the referred files are compiled into the same \fileext{qlf} file. Other directives will be stored in the \fileext{qlf} file and executed in the same fashion as when loading the \fileext{pl} file. For term_expansion/2, the same rules as described in \secref{compilation} apply. Source references (source_file/2) in the Quick Load File refer to the Prolog source file from which the compiled code originates. \predicate{qload}{1}{+File} Loads the `Quick Load File'. It has the same semantics as consult/1 for a normal sourcefile. Equivalent to \exam{consult(\arg{File})} iff \arg{File} refers to a `Quick Load File'. \end{description} \section{Listing Predicates and Editor Interface} \label{sec:listing} SWI-Prolog offers an interface to the Unix \program{vi} editor and the GNU~Emacs invocations \program{emacs} and \program{emacsclient}. Which editor is used is determined by the Unix environment variable \env{EDITOR}, which should hold the full pathname of the editor. If this variable is not defined, \program{vi} is used.% \footnote{When using XPCE, you may wish to load \file{library('emacs/swi_prolog')} to use XPCE/Prolog's built-in editor.} After the user quits the editor, make/0 is invoked to reload all modified source files using consult/1. If the editor can be quit such that an exit status non-equal to 0 is returned make/0 will not be invoked. \arg{top} can do this by typing control-C, \arg{vi} cannot do this. A predicate specification is either a term with the same functor and arity as the predicate wanted, a term of the form \arg{Functor}/\arg{Arity} or a single atom. In the latter case the database is searched for a predicate of this name and arbitrary arity (see current_predicate/2). When more than one such predicate exists the system will prompt for confirmation on each of the matched predicates. Predicates specifications are given to the `Do What I Mean' system (see dwim_predicate/2) if the requested predicate does not exist. \begin{description} \predicate{ed}{1}{+Pred} Invoke the user's preferred editor on the source file of \arg{Pred}, providing a search specification which searches for the predicate at the start of a line. \predicate{ed}{0}{} Invoke ed/1 on the predicate last edited using ed/1. Asks the user to confirm before starting the editor. \predicate{edit}{1}{+File} Invoke the user's preferred editor on \arg{File}. \arg{File} is a file specification as for consult/1 (but not a list). Note that the file should exist. \predicate{edit}{0}{} Invoke edit/1 on the file last edited using edit/1. Asks the user to confirm before starting the editor. \predicate{listing}{1}{+Pred} List specified predicates (when an atom is given all predicates with this name will be listed). The listing is produced on the basis of the internal representation, thus loosing user's layout and variable name information. See also portray_clause/1. \predicate{listing}{0}{} List all predicates of the database using listing/1. \predicate{portray_clause}{1}{+Clause} Pretty print a clause as good as we can. A clause should be specified as a term `\exam{<Head> :- <Body>}' (put brackets around it to avoid operator precedence problems). Facts are represented as `\exam{<Head> :- true}'. \predicate{edit_source}{1}{+Spec} A hook that may be defined in the module \const{user} to specify how the predicates ed/1 and edit/1 call the editor. If ed/1 is invoking this hook, \arg{Spec} is a term of the format \begin{quote} \exam{\arg{File}:\arg{LineNo}:\arg{Name}/\arg{Arity}} \end{quote} Where \arg{File} and \arg{LineNo} represents the location of the predicate remembered by Prolog, and \arg{Name} and \arg{Arity} specify the predicate. If invoked by edit/1, \arg{Spec} is an atom denoting the name of the file to be edited. This hook is defined by the library \pllib{swi_prolog} distributed with the XPCE package for using XPCE to edit Prolog files. \end{description} \section{Verify Type of a Term} \begin{description} \predicate{var}{1}{+Term} Succeeds if \arg{Term} currently is a free variable. \predicate{nonvar}{1}{+Term} Succeeds if \arg{Term} currently is not a free variable. \predicate{integer}{1}{+Term} Succeeds if \arg{Term} is bound to an integer. \predicate{float}{1}{+Term} Succeeds if \arg{Term} is bound to a floating point number. \predicate{number}{1}{+Term} Succeeds if \arg{Term} is bound to an integer or a floating point number. \predicate{atom}{1}{+Term} Succeeds if \arg{Term} is bound to an atom. \predicate{string}{1}{+Term} Succeeds if \arg{Term} is bound to a string. \predicate{atomic}{1}{+Term} Succeeds if \arg{Term} is bound to an atom, string, integer or floating point number. \predicate{compound}{1}{+Term} Succeeds if \arg{Term} is bound to a compound term. See also functor/3 and =../2. \predicate{ground}{1}{+Term} Succeeds if \arg{Term} holds no free variables. \end{description} \section{Comparison and Unification or Terms} \label{sec:compare} \subsection{Standard Order of Terms} Comparison and unification of arbitrary terms. Terms are ordered in the so called ``standard order''. This order is defined as follows: \begin{enumerate} \item $\arg{Variables} < \arg{Atoms} < \arg{Strings}% \footnote{Strings might be considered atoms in future versions. See also \secref{strings}} < \arg{Numbers} < \arg{Terms}$ \item $\arg{Old~Variable} < \arg{New~Variable}$% \footnote{In fact the variables are compared on their (dereferenced) addresses. Variables living on the global stack are always $<$ than variables on the local stack. Programs should not rely on the order in which variables are sorted.} \item \arg{Atoms} are compared alphabetically. \item \arg{Strings} are compared alphabetically. \item \arg{Numbers} are compared by value. Integers and floats are treated identically. \item \arg{Terms} are first checked on their functor (alphabetically), then on their arity and finally recursively on their arguments, leftmost argument first. \end{enumerate} \begin{description} \infixop{==}{+Term1}{+Term2} Succeeds if \arg{Term1} is equivalent to \arg{Term2}. A variable is only identical to a sharing variable. \infixop{\==}{+Term1}{+Term2} Equivalent to \exam{\Snot Term1 == Term2}. \infixop{=}{+Term1}{+Term2} Unify \arg{Term1} with \arg{Term2}. Succeeds if the unification succeeds. \infixop{\=}{+Term1}{+Term2} Equivalent to \exam{\Snot Term1 = Term2}. \infixop{=@=}{+Term1}{+Term2} Succeeds if \arg{Term1} is `structurally equal' to \arg{Term2}. Structural equivalence is weaker than equivalence (\predref{==}{2}), but stronger than unification (\predref{=}{2}). Two terms are structurally equal if their tree representation is identical and they have the same `pattern' of variables. Examples: \begin{quote} \begin{tabular}{rclc} \tt a & \tt =@= & \tt A & false \\ \tt A & \tt =@= & \tt B & true \\ \tt x(A,A) & \tt =@= & \tt x(B,C) & false \\ \tt x(A,A) & \tt =@= & \tt x(B,B) & true \\ \tt x(A,B) & \tt =@= & \tt x(C,D) & true \\ \end{tabular} \end{quote} \infixop{\=@=}{+Term1}{+Term2} Equivalent to \exam{`\Snot Term1 =@= Term2'}. \infixop{@<}{+Term1}{+Term2} Succeeds if \arg{Term1} is before \arg{Term2} in the standard order of terms. \infixop{@=<}{+Term1}{+Term2} Succeeds if both terms are equal (\predref{==}{2}) or \arg{Term1} is before \arg{Term2} in the standard order of terms. \infixop{@>}{+Term1}{+Term2} Succeeds if \arg{Term1} is after \arg{Term2} in the standard order of terms. \infixop{@>=}{+Term1}{+Term2} Succeeds if both terms are equal (\predref{==}{2}) or \arg{Term1} is after \arg{Term2} in the standard order of terms. \predicate{compare}{3}{?Order, +Term1, +Term2} Determine or test the \arg{Order} between two terms in the standard order of terms. \arg{Order} is one of \const{<}, \const{>} or \const{=}, with the obvious meaning. \end{description} \section{Control Predicates} The predicates of this section implement control structures. Normally these constructs are translated into virtual machine instructions by the compiler. It is still necessary to implement these constructs as true predicates to support meta-calls, as demonstrated in the example below. The predicate finds all currently defined atoms of 1 character long. Note that the cut has no effect when called via one of these predicates (see !/0). \begin{code} one_character_atoms(As) :- findall(A, (current_atom(A), atom_length(A, 1)), As). \end{code} \begin{description} \predicate{fail}{0}{} Always fail. The predicate fail/0 is translated into a single virtual machine instruction. \predicate{true}{0}{} Always succeed. The predicate true/0 is translated into a single virtual machine instruction. \predicate{repeat}{0}{} Always succeed, provide an infinite number of choice points. \predicate{!}{0}{} Cut. Discard choice points of parent frame and frames created after the parent frame. Note that the control structures \predref{;}{2}, \predref{|}{2}, \predref{->}{2} and \predref{\+}{1} are normally handled by the compiler and do not create a frame, which implies the cut operates through these predicates. Some examples are given below. Note the difference between {t3}/1 and {t4}/1. Also note the effect of call/1 in {t5}/0. As the argument of call/1 is evaluated by predicates rather than the compiler the cut has no effect. \begin{center}\begin{tabular}{ll} \exam{t1 :- (a, !, fail ; b).} & \% cuts {a}/0 and {t1}/0 \\ \exam{t2 :- (a -> b, ! ; c).} & \% cuts {b}/0 and {t2}/0 \\ \exam{t3(G) :- a, G, fail.} & \% if `G = !' cuts {a}/0 and {t1}/1 \\ \exam{t4(G) :- a, call(G), fail.} & \% if `G = !' cut has no effect \\ \exam{t5 :- call((a, !, fail ; b)).} & \% Cut has no effect \\ \exam{t6 :- \Snot (a, !, fail ; b).}& \% cuts {a}/0 and {t6}/0 \\ \end{tabular}\end{center} \infixop{,}{+Goal1}{+Goal2} Conjunction. Succeeds if both `Goal1' and `Goal2' can be proved. It is defined as (this definition does not lead to a loop as the second comma is handled by the compiler): \begin{code} Goal1, Goal2 :- Goal1, Goal2. \end{code} \infixop{;}{+Goal1}{+Goal2} The `or' predicate is defined as: \begin{code} Goal1 ; _Goal2 :- Goal1. _Goal1 ; Goal2 :- Goal2. \end{code} \infixop{|}{+Goal1}{+Goal2} Equivalent to \predref{;}{2}. Retained for compatibility only. New code should use \predref{;}{2}. Still nice though for grammar rules. \infixop{->}{+Condition}{+Action} If-then and If-Then-Else. The \predref{->}{2} construct commits to the choices made at its left-hand side, destroying choice-points created inside the clause (by \predref{;}{2}), or by goals called by this clause. Unlike \predref{!}{0}, the choicepoint of the predicate as a whole (due to multiple clauses) is \strong{not} destroyed. The combination \predref{;}{2} and \predref{->}{2} is defines as: \begin{code} If -> Then; _Else :- If, !, Then. If -> _Then; Else :- !, Else. If -> Then :- If, !, Then. \end{code} Note that the operator precedence relation between \const{;} and \const{->} ensure \exam{If -> Then ; Else} is actually a term of the form \exam{;(->(If, Then), Else)}. The first two clauses belong to the definition of \predref{;}{2}), while only the last defines \predref{->}{2}. \infixop{*->}{+Condition}{+Action ; +Else} This construct implements the so-called `soft-cut'. The control is defined as follows: If \arg{Condition} succeeds at least once, the semantics is the same as (\arg{Condition}, \arg{Action}). If \arg{Condition} does not succeed, the semantics is that of (\arg{Condition}, \arg{Else}). In other words, If \arg{Condition} succeeds at least once, simply behave as the conjunction of \arg{Condition} and \arg{Action}, otherwise execute \arg{Else}. \prefixop{\+}{+Goal} Succeeds if `Goal' cannot be proven (mnemonic: \chr{+} refers to {\em provable} and the backslash (\chr{\}) is normally used to indicate negation). \end{description} \section{Meta-Call Predicates} \label{sec:metacall} Meta call predicates are used to call terms constructed at run time. The basic meta-call mechanism offered by SWI-Prolog is to use variables as a subclause (which should of course be bound to a valid goal at runtime). A meta-call is slower than a normal call as it involves actually searching the database at runtime for the predicate, while for normal calls this search is done at compile time. \begin{description} \predicate{call}{1}{+Goal} Invoke \arg{Goal} as a goal. Note that clauses may have variables as subclauses, which is identical to call/1, except when the argument is bound to the cut. See \predref{!}{0}. \predicate{call}{2}{+Goal, +ExtraArg1, \ldots} % 2.. Append \arg{ExtraArg1, ExtraArg2, \ldots} to the argument list of \arg{Goal} and call the result. For example, \exam{call(plus(1), 2, X)} will call plus/3, binding \arg{X} to 3. The call/[2..] construct is handled by the compiler, which implies that redefinition as a predicate has no effect. The predicates call/[2-6] are defined as true predicates, so they can be handled by interpreted code. \predicate{apply}{2}{+Term, +List} Append the members of \arg{List} to the arguments of \arg{Term} and call the resulting term. For example: \exam{apply(plus(1), [2, X])} will call \exam{plus(1, 2, X)}. apply/2 is incorporated in the virtual machine of SWI-Prolog. This implies that the overhead can be compared to the overhead of call/1. New code should use call/[2..] if the length of \arg{List} is fixed, which is more widely supported and faster because there is no need to build and examine the argument list. \predicate{not}{1}{+Goal} Succeeds when \arg{Goal} cannot be proven. Retained for compatibility only. New code should use \predref{\+}{1}. \predicate{once}{1}{+Goal} Defined as: \begin{code} once(Goal) :- Goal, !. \end{code} once/1 can in many cases be replaced with \predref{->}{2}. The only difference is how the cut behaves (see !/0). The following two clauses are identical: \begin{code} 1) a :- once((b, c)), d. 2) a :- b, c -> d. \end{code} \predicate{ignore}{1}{+Goal} Calls \arg{Goal} as once/1, but succeeds, regardless of whether \arg{Goal} succeeded or not. Defined as: \begin{code} ignore(Goal) :- Goal, !. ignore(_). \end{code} \predicate{call_with_depth_limit}{3}{+Goal, +Limit, -Result} If \arg{Goal} can be proven without recursion deeper than \arg{Limit} levels, call_with_depth_limit/3 succeeds, binding \arg{Result} to the deepest recursion level used during the proof. Otherwise, \arg{Result} is unified with \const{depth_limit_exceeded} if the limit was exceeded during the proof, or the entire predicate fails if \arg{Goal} fails without exceeding \arg{Limit}. The depth-limit is guarded by the internal machinery. This differ from the depth computed based on a theoretical model. For example, true/0 is translated into an inlined virtual machine instruction. Also, repeat/0 is not implemented as below, but as a non-deterministic foreign predicate. \begin{code} repeat. repeat :- repeat. \end{code} As a result, call_with_depth_limit/3 may still loop inifitly on programs that should theoretically finish in finite time. This problem can be cured by using Prolog equivalents to such built-in predicates. This predicate may be used for theorem-provers to realise techniques like \jargon{iterrative deepening}. It was implemented after discussion with Steve Moyle \email{smoyle@ermine.ox.ac.uk}. \end{description} \section{ISO compliant Exception handling} \label{sec:exception} SWI-Prolog defines the predicates catch/3 and throw/1 for ISO compliant raising and catching of exceptions. In the current implementation (2.9.0), only part of the built-in predicates generate exceptions. In general, exceptions are implemented for I/O and arithmetic. \begin{description} \predicate{catch}{3}{:Goal, +Catcher, :Recover} Behaves as call/1 if no exception is raised when executing \arg{Goal}. If a exception is raised using throw/1 while \arg{Goal} executes, and the \arg{Goal} is the innermost goal for which \arg{Catcher} unifies with the argument of throw/1, all choicepoints generated by \arg{Goal} are cut, and \arg{Recover} is called as in call/1. The overhead of calling a goal through catch/3 is very comparable to call/1. Recovery from an exception has a similar overhead. \predicate{throw}{1}{+Exception} Raise an exception. The system will look for the innermost catch/3 ancestor for which \arg{Exception} unifies with the \arg{Catcher} argument of the catch/3 call. See catch/3 for details. If there is no catch/3 willing to catch the error in the current Prolog context, the toplevel (prolog/0) catches the error and prints a warning message. If an exception was raised in a callback from C (see \chapref{foreign}), PL_next_solution() will fail and the exception context can be retrieved using PL_exception(). \end{description} \subsection{Debugging and exceptions} \index{exceptions,debugging}% \index{debugging,exceptions}% Before the introduction of exceptions in SWI-Prolog a runtime error was handled by printing an error message, after which the predicate failed. If the feature (see feature/2) \const{debug_on_error} was in effect (default), the tracer was switched on. The combination of the error message and trace information is generally sufficient to locate the error. With exception handling, things are different. A programmer may wish to trap an exception using catch/3 to avoid it reaching the user. If the exception is not handled by user-code, the interactive toplevel will trap it to prevent termination. If we do not take special precautions, the context information associated with an unexpected exception (i.e.\ a programming error) is lost. Therefore, if an exception is raised, which is not caught using catch/3 and the toplevel is running, the error will be printed, and the system will enter trace mode. If the system is in an non-interactive callback from foreign code and there is no catch/3 active in the current context, it cannot determine whether or not the exception will be caught by the external routine calling Prolog. It will then base its behaviour on the feature debug_on_error: \begin{itemlist} \item [feature(debug_on_error, false)] The exception does not trap the debugger and is returned to the foreign routine calling Prolog, where it can be accessed using PL_exception(). This is the default. \item [feature(debug_on_error, true)] If the exception is not caught by Prolog in the current context, it will trap the tracer to help analysing the context of the error. \end{itemlist} While looking for the context in which an exception takes place, it is adviced to switch on debug mode using the predicate debug/0. \subsection{The exception term} \label{sec:exceptterm} Builtin predicates generates exceptions using a term \term{error}{Formal, Context}. The first argument is the `formal' description of the error, specifying the class and generic defined context information. When applicable, the ISO error-term definition is used. The second part describes some additional context to help the programmer while debugging. In its most generic form this is a term of the form \term{context}{Name/Arity, Message}, where \arg{Name}/\arg{Arity} describes the built-in predicate that raised the error, and \arg{Message} provides an additional description of the error. Any part of this structure may be a variable if no information was present. \subsection{Printing a message from an exception} The predicate print_message/2 may be used to print an exception term in a human readable format: \begin{description} \predicate{print_message}{2}{+Kind, +Term} This predicate is modelled after the Quintus predicate with the same name, though its current implementation is incomplete. It is used only for printing messages from exceptions from built-in predicates. \arg{Kind} is one of \const{informational}, \const{warning}, const{error}, \const{help} or \const{silent}. Currently only \const{error} is defined. \arg{Term} is an \funcref{error}{2} term described in \secref{exceptterm}. A human-readable message is printed to the stream \const{user_error}. This predicate first obtains the `human translation' of \arg{Term} and then calls message_hook/3. If this fails the message is printed to the stream \const{user_error}. The print_message/2 predicate and its rules are in the file \file{<plhome>/boot/messages.pl}, which may be inspected for more information on the error messages and related error terms. \predicate{message_hook}{3}{+Term, +Kind, +Message} Hook predicate that may be define in the module \const{user} to intercept messages from print_message/2. \arg{Term} and \arg{Kind} are the same as passed to print_message/2. \arg{Message} is a string containing the human readable translation of the message. If this predicate succeeds, print_message/2 considers the message printed. This predicate should be defined dynamic and multifile to allow other modules defining clauses for it too. \end{description} \section{Advanced control-structures: blocks} \index{exception-handling} The predicates of this section form a tightly related set for realising premature successful or failing exits from a \arg{block}. These predicates are first of all useful for error-recovery. They were primarily implemented for compatibility reasons. \begin{description} \predicate{block}{3}{+Label, +Goal, -ExitValue} Execute \arg{Goal} in a \arg{block}. \arg{Label} is the name of the block. \arg{Label} is normally an atom, but the system imposes no type constraints and may even be a variable. \arg{ExitValue} is normally unified to the second argument of an exit/2 call invoked by \arg{Goal}. \predicate{exit}{2}{+Label, +Value} Calling exit/2 makes the innermost \arg{block} which \arg{Label} unifies exit. The block's \arg{ExitValue} is unified with \arg{Value}. If this unification fails the block fails. \predicate{fail}{1}{+Label} Calling fail/1 makes the innermost \arg{block} which \arg{Label} unifies fail immediately. Implemented as \begin{code} fail(Label) :- !(Label), fail. \end{code} \predicate{!}{1}{+Label} Cut all choice-points created since the entry of the innermost \arg{block} which \arg{Label} unifies. \end{description} The example below illustrate these constructs to immediately report a syntax-error from a `deep-down' procedure to the outside world without passing it as an argument `all-over-the-place'. \begin{code} parse(RuleSet, InputList, Rest) :- block(syntaxerror, phrase(RuleSet, InputList, Rest), Error), ( var(Error) -> true ; format('Syntax-error: ~w~n', Error), fail ). integer(N) --> digit(D1), !, digits(Ds), { name(N, [D1|Ds]) }. digits([D|R]) --> digit(D), digits(R). digits(_) --> letter(_), !, { exit(syntaxerror, 'Illegal number') }. digits([]) --> []. digit(D, [D|R], R) :- between(0'0, 0'9, D). letter(D, [D|R], R) :- between(0'a, 0'z, D). \end{code} \section{Grammar rule interface (phrase)} The predicates below may be called to activate a grammar-rule set: \begin{description} \predicate{phrase}{2}{+RuleSet, +InputList} Equivalent to \exam{phrase(\arg{RuleSet}, \arg{InputList}, [])}. \predicate{phrase}{3}{+RuleSet, +InputList, -Rest} Activate the rule-set with given name. `InputList' is the list of tokens to parse, `Rest' is unified with the remaining tokens if the sentence is parsed correctly. \end{description} \section{Database} SWI-Prolog offers three different database mechanisms. The first one is the common assert/retract mechanism for manipulating the clause database. As facts and clauses asserted using assert/1 or one of its derivatives become part of the program these predicates compile the term given to them. retract/1 and retractall/1 have to unify a term and therefore have to decompile the program. For these reasons the assert/retract mechanism is expensive. On the other hand, once compiled, queries to the database are faster than querying the recorded database discussed below. See also dynamic/1. The second way of storing arbitrary terms in the database is using the ``recorded database''. In this database terms are associated with a \arg{key}. A key can be an atom, integer or term. In the last case only the functor and arity determine the key. Each key has a chain of terms associated with it. New terms can be added either at the head or at the tail of this chain. This mechanism is considerably faster than the assert/retract mechanism as terms are not compiled, but just copied into the heap. The third mechanism is a special purpose one. It associates an integer or atom with a key, which is an atom, integer or term. Each key can only have one atom or integer associated with it. It again is considerably faster than the mechanisms described above, but can only be used to store simple status information like counters, etc. \begin{description} \predicate{abolish}{1}{:PredicateIndicator} Removes all clauses of a predicate with functor \arg{Functor} and arity \arg{Arity} from the database. Unlike version 1.2, all predicate attributes (dynamic, multifile, index, etc.) are reset to their defaults. Abolishing an imported predicate only removes the import link; the predicate will keep its old definition in its definition module. For `cleanup' of the dynamic database, one should use retractall/1 rather than abolish/2. \predicate{abolish}{2}{+Name, +Arity} Same as \exam{abolish(Name/Arity)}. The predicate abolish/2 conforms to the Edinburgh standard, while abolish/1 is ISO compliant. \predicate{redefine_system_predicate}{1}{+Head} This directive may be used both in module \const{user} and in normal modules to redefine any system predicate. If the system definition is redefined in module \const{user}, the new definition is the default definition for all sub-modules. Otherwise the redefinition is local to the module. The system definition remains in the module \const{system}. Redefining system predicate facilitates the definition of compatibility packages. Use in other context is discouraged. \predicate{retract}{1}{+Term} When \arg{Term} is an atom or a term it is unified with the first unifying fact or clause in the database. The fact or clause is removed from the database. \predicate{retractall}{1}{+Head} All facts or clauses in the database for which the \arg{head} unifies with \arg{Head} are removed.% \footnote{Note that the definition has changed since version 2.0.6. See release notes.} \predicate{assert}{1}{+Term} Assert a fact or clause in the database. \arg{Term} is asserted as the last fact or clause of the corresponding predicate. \predicate{asserta}{1}{+Term} Equivalent to assert/1, but \arg{Term} is asserted as first clause or fact of the predicate. \predicate{assertz}{1}{+Term} Equivalent to assert/1. \predicate{assert}{2}{+Term, -Reference} Equivalent to assert/1, but \arg{Reference} is unified with a unique reference to the asserted clause. This key can later be used with clause/3 or erase/1. \predicate{asserta}{2}{+Term, -Reference} Equivalent to assert/2, but \arg{Term} is asserted as first clause or fact of the predicate. \predicate{assertz}{2}{+Term, -Reference} Equivalent to assert/2. \predicate{recorda}{3}{+Key, +Term, -Reference} Assert \arg{Term} in the recorded database under key \arg{Key}. \arg{Key} is an integer, atom or term. \arg{Reference} is unified with a unique reference to the record (see erase/1). \predicate{recorda}{2}{+Key, +Term} Equivalent to \exam{recorda(\arg{Key}, \arg{Value}, _)}. \predicate{recordz}{3}{+Key, +Term, -Reference} Equivalent to recorda/3, but puts the \arg{Term} at the tail of the terms recorded under \arg{Key}. \predicate{recordz}{2}{+Key, +Term} Equivalent to \exam{recordz(\arg{Key}, \arg{Value}, _)}. \predicate{recorded}{3}{+Key, -Value, -Reference} Unify \arg{Value} with the first term recorded under \arg{Key} which does unify. \arg{Reference} is unified with the memory location of the record. \predicate{recorded}{2}{+Key, -Value} Equivalent to \exam{recorded(\arg{Key}, \arg{Value}, _)}. \predicate{erase}{1}{+Reference} Erase a record or clause from the database. \arg{Reference} is an integer returned by recorda/3 or recorded/3, clause/3, assert/2, asserta/2 or assertz/2. Other integers might conflict with the internal consistency of the system. Erase can only be called once on a record or clause. A second call also might conflict with the internal consistency of the system.% \bug{The system should have a special type for pointers, thus avoiding the Prolog user having to worry about consistency matters. Currently some simple heuristics are used to determine whether a reference is valid.} \predicate{flag}{3}{+Key, -Old, +New} \arg{Key} is an atom, integer or term. Unify \arg{Old} with the old value associated with \arg{Key}. If the key is used for the first time \arg{Old} is unified with the integer 0. Then store the value of \arg{New}, which should be an integer, float, atom or arithmetic expression, under \arg{Key}. flag/3 is a very fast mechanism for storing simple facts in the database. Example: \begin{code} :- module_transparent succeeds_n_times/2. succeeds_n_times(Goal, Times) :- flag(succeeds_n_times, Old, 0), Goal, flag(succeeds_n_times, N, N+1), fail ; flag(succeeds_n_times, Times, Old). \end{code} \end{description} \subsection{Indexing databases} By default, SWI-Prolog, as most other implementations, indexes predicates on their first argument. SWI-Prolog allows indexing on other and multiple arguments using the declaration index/1. For advanced database indexing, it defines hash_term/2: \begin{description} \predicate{hash_term}{2}{+Term, -HashKey} If \arg{Term} is a ground term (see ground/1), \arg{HashKey} is unified with a positive integer value that may be used as a hash-key to the value. If \arg{Term} is not ground, the predicate succeeds immediately, leaving \arg{HashKey} an unbound variable. This predicate may be used to build hash-tables as well as to exploit argument-indexing to find complex terms more quickly. The hash-key does not rely on temporary information like addresses of atoms and may be assumed constant over different invocations of SWI-Prolog. \end{description} \section{Declaring Properties of Predicates} \label{ch:dynamic} \label{sec:declare} This section describes directives which manipulate attributes of predicate definitions. The functors dynamic/1, multifile/1 and discontiguous/1 are operators of priority 1150 (see op/3), which implies the list of predicates they involve can just be a comma separated list: \begin{code} :- dynamic foo/0, baz/2. \end{code} On SWI-Prolog all these directives are just predicates. This implies they can also be called by a program. Do not rely on this feature if you want to maintain portability to other Prolog implementations. \begin{description} \prefixop{dynamic}{+Functor/+Arity, \ldots} Informs the interpreter that the definition of the predicate(s) may change during execution (using assert/1 and/or retract/1). Currently dynamic/1 only stops the interpreter from complaining about undefined predicates (see unknown/2). Future releases might prohibit assert/1 and retract/1 for not-dynamic declared procedures. \prefixop{multifile}{+Functor/+Arity, \ldots} Informs the system that the specified predicate(s) may be defined over more than one file. This stops consult/1 from redefining a predicate when a new definition is found. \prefixop{discontiguous}{+Functor/+Arity, \ldots} Informs the system that the clauses of the specified predicate(s) might not be together in the source file. See also style_check/1. \predicate{index}{1}{+Head} Index the clauses of the predicate with the same name and arity as \arg{Head} on the specified arguments. \arg{Head} is a term of which all arguments are either `1' (denoting `index this argument') or `0' (denoting `do not index this argument'). Indexing has no implications for the semantics of a predicate, only on its performance. If indexing is enabled on a predicate a special purpose algorithm is used to select candidate clauses based on the actual arguments of the goal. This algorithm checks whether indexed arguments might unify in the clause head. Only atoms, integers and functors (e.g. name and arity of a term) are considered. Indexing is very useful for predicates with many clauses representing facts. Due to the representation technique used at most 4 arguments can be indexed. All indexed arguments should be in the first 32 arguments of the predicate. If more than 4 arguments are specified for indexing only the first 4 will be accepted. Arguments above 32 are ignored for indexing. By default all predicates with $<arity> \geq 1$ are indexed on their first argument. It is possible to redefine indexing on predicates that already have clauses attached to them. This will initiate a scan through the predicates clause list to update the index summary information stored with each clause. If---for example---one wants to represents sub-types using a fact list \mbox{`sub_type(Sub, Super)'} that should be used both to determine sub- and super types one should declare {sub_type}/2 as follows: \begin{code} :- index(sub_type(1, 1)). sub_type(horse, animal). \end{code} \end{description} \section{Examining the Program} \begin{description} \predicate{current_atom}{1}{-Atom} Successively unifies \arg{Atom} with all atoms known to the system. Note that current_atom/1 always succeeds if \arg{Atom} is instantiated to an atom. \predicate{current_functor}{2}{?Name, ?Arity} Successively unifies \arg{Name} with the name and \arg{Arity} with the arity of functors known to the system. \predicate{current_flag}{1}{-FlagKey} Successively unifies \arg{FlagKey} with all keys used for flags (see flag/3). \predicate{current_key}{1}{-Key} Successively unifies \arg{Key} with all keys used for records (see recorda/3, etc.). \predicate{current_predicate}{2}{?Name, ?Head} Successively unifies \arg{Name} with the name of predicates currently defined and \arg{Head} with the most general term built from \arg{Name} and the arity of the predicate. This predicate succeeds for all predicates defined in the specified module, imported to it, or in one of the modules from which the predicate will be imported if it is called. \predicate{predicate_property}{2}{?Head, ?Property} Succeeds if \arg{Head} refers to a predicate that has property \arg{Property}. Can be used to test whether a predicate has a certain property, obtain all properties known for \arg{Head}, find all predicates having \arg{property} or even obtaining all information available about the current program. \arg{Property} is one of: \begin{description} \termitem{interpreted}{} Is true if the predicate is defined in Prolog. We return true on this because, although the code is actually compiled, it is completely transparent, just like interpreted code. \termitem{built_in}{} Is true if the predicate is locked as a built-in predicate. This implies it cannot be redefined in its definition module and it can normally not be seen in the tracer. \termitem{foreign}{} Is true if the predicate is defined in the C language. \termitem{dynamic}{} Is true if the predicate is declared dynamic using the dynamic/1 declaration. \termitem{multifile}{} Is true if the predicate is declared multifile using the multifile/1 declaration. \termitem{undefined}{} Is true if a procedure definition block for the predicate exists, but there are no clauses in it and it is not declared dynamic. This is true if the predicate occurs in the body of a loaded predicate, an attempt to call it has been made via one of the meta-call predicates or the predicate had a definition in the past. See the library package \arg{check} for example usage. \termitem{transparent}{} Is true if the predicate is declared transparent using the module_transparent/1 declaration. \termitem{exported}{} Is true if the predicate is in the public list of the context module. \termitem{imported_from}{Module} Is true if the predicate is imported into the context module from module \arg{Module}. \termitem{indexed}{Head} Predicate is indexed (see index/1) according to \arg{Head}. \arg{Head} is a term whose name and arity are identical to the predicate. The arguments are unified with `1' for indexed arguments, `0' otherwise. \termitem{file}{FileName} Unify \arg{FileName} with the name of the sourcefile in which the predicate is defined. See also source_file/2. \termitem{line_count}{LineNumber} Unify \arg{LineNumber} with the line number of the first clause of the predicate. Fails if the predicate is not associated with a file. See also source_file/2. \termitem{number_of_clauses}{ClauseCount} Unify \arg{ClauseCount} to the number of clauses associated with the predicate. Fails for foreign predicates. \end{description} \predicate{dwim_predicate}{2}{+Term, -Dwim} `Do What I Mean' (`dwim') support predicate. \arg{Term} is a term, which name and arity are used as a predicate specification. \arg{Dwim} is instantiated with the most general term built from \arg{Name} and the arity of a defined predicate that matches the predicate specified by \arg{Term} in the `Do What I Mean' sense. See dwim_match/2 for `Do What I Mean' string matching. Internal system predicates are not generated, unless \exam{style_check(+dollar)} is active. Backtracking provides all alternative matches. \predicate{clause}{2}{?Head, ?Body} Succeeds when \arg{Head} can be unified with a clause head and \arg{Body} with the corresponding clause body. Gives alternative clauses on backtracking. For facts \arg{Body} is unified with the atom \arg{true}. Normally clause/2 is used to find clause definitions for a predicate, but it can also be used to find clause heads for some body template. \predicate{clause}{3}{?Head, ?Body, ?Reference} Equivalent to clause/2, but unifies \arg{Reference} with a unique reference to the clause (see also assert/2, erase/1). If \arg{Reference} is instantiated to a reference the clause's head and body will be unified with \arg{ Head} and \arg{Body}. \predicate{nth_clause}{3}{?Pred, ?Index, ?Reference} Provides access to the clauses of a predicate using their index number. Counting starts at 1. If \arg{Reference} is specified it unifies \arg{Pred} with the most general term with the same name/arity as the predicate and \arg{Index} with the index-number of the clause. Otherwise the name and arity of \arg{Pred} are used to determine the predicate. If \arg{Index} is provided \arg{Reference} will be unified with the clause reference. If \arg{Index} is unbound, backtracking will yield both the indices and the references of all clauses of the predicate. The following example finds the 2nd clause of member/2: \begin{code} ?- nth_clause(member(_,_), 2, Ref), clause(Head, Body, Ref). Ref = 160088 Head = system : member(G575, [G578|G579]) Body = member(G575, G579) \end{code} \predicate{clause_property}{2}{+ClauseRef, -Property} Queries properties of a clause. \arg{ClauseRef} is a reference to a clause as produced by clause/3, nth_clause/3 or prolog_frame_attribute/3. \arg{Property} is one of the following: \begin{description} \termitem{file}{FileName} Unify \arg{FileName} with the name of the sourcefile in which the clause is defined. Fails if the clause is not associated to a file. \termitem{line_count}{LineNumber} Unify \arg{LineNumber} with the line number of the clause. Fails if the clause is not associated to a file. \termitem{fact}{} True if the clause has no body. \termitem{erased}{} True if the clause has been erased, but not yet reclaimed because it is referenced. \end{description} \end{description} \section{Input and Output} SWI-Prolog provides two different packages for input and output. One confirms to the Edinburgh standard. This package has a notion of `current-input' and `current-output'. The reading and writing predicates implicitly refer to these streams. In the second package, streams are opened explicitly and the resulting handle is used as an argument to the reading and writing predicate to specify the source or destination. Both packages are fully integrated; the user may switch freely between them. \subsection{Input and Output Using Implicit Source and Destination} The package for implicit input and output destination is upwards compatible to DEC-10 and C-Prolog. The reading and writing predicates refer to resp. the current input- and output stream. Initially these streams are connected to the terminal. The current output stream is changed using tell/1 or append/1. The current input stream is changed using see/1. The streams current value can be obtained using telling/1 for output- and seeing/1 for input streams. The table below shows the valid stream specifications. The reserved names \const{user_input}, \const{user_output} and \const{user_error} are for neat integration with the explicit streams. \begin{center} \begin{tabular}{|l|p{3in}|} \hline \const{user} & This reserved name refers to the terminal \\ \const{user_input} & Input from the terminal \\ \const{user_output} & Output to the terminal \\ \const{user_error} & Unix error stream (output only) \\ <Atom> & Name of a Unix file \\ \const{pipe(<Atom>)} & Name of a Unix command \\ \hline \end{tabular} \end{center} Source and destination are either a file, one of the reserved words above, or a term `pipe(\arg{Command})'. In the predicate descriptions below we will call the source/destination argument `\arg{SrcDest}'. Below are some examples of source/destination specifications. \begin{center}\begin{tabular}{ll} \exam{?- see(data).} & \% Start reading from file `data'. \\ \exam{?- tell(stderr).} & \% Start writing on the error stream. \\ \exam{?- tell(pipe(lpr)).} & \% Start writing to the printer. \end{tabular}\end{center} Another example of using the \functor{pipe}{1} construct is shown below. Note that the \functor{pipe}{1} construct is not part of Prolog's standard I/O repertoire. \begin{code} getwd(Wd) :- seeing(Old), see(pipe(pwd)), collect_wd(String), seen, see(Old), atom_chars(Wd, String). collect_wd([C|R]) :- get0(C), C \== -1, !, collect_wd(R). collect_wd([]). \end{code} \begin{description} \predicate{see}{1}{+SrcDest} Make \arg{SrcDest} the current input stream. If \arg{SrcDest} was already opened for reading with see/1 and has not been closed since, reading will be resumed. Otherwise \arg{SrcDest} will be opened and the file pointer is positioned at the start of the file. \predicate{tell}{1}{+SrcDest} Make \arg{SrcDest} the current output stream. If \arg{SrcDest} was already opened for writing with tell/1 or append/1 and has not been closed since, writing will be resumed. Otherwise the file is created or---when existing---truncated. See also append/1. \predicate{append}{1}{+File} Similar to tell/1, but positions the file pointer at the end of \arg{File} rather than truncating an existing file. The pipe construct is not accepted by this predicate. \predicate{seeing}{1}{?SrcDest} Unify the name of the current input stream with \arg{SrcDest}. \predicate{telling}{1}{?SrcDest} Unify the name of the current output stream with \arg{SrcDest}. \predicate{seen}{0}{} Close the current input stream. The new input stream becomes \arg{user}. \predicate{told}{0}{} Close the current output stream. The new output stream becomes \arg{user}. \end{description} \subsection{Explicit Input and Output Streams} The predicates below are part of the Quintus compatible stream-based I/O package. In this package streams are explicitly created using the predicate open/3. The resulting stream identifier is then passed as a parameter to the reading and writing predicates to specify the source or destination of the data. \begin{description} \predicate{open}{4}{+SrcDest, +Mode, -Stream, +Options} ISO compliant predicate to open a stream. \arg{SrcDes} is either an atom, specifying a Unix file, or a term `\exam{pipe(\arg{Command})}', just like see/1 and tell/1. \arg{Mode} is one of \const{read}, \const{write}, \const{append} or \const{update}. Mode \const{append} opens the file for writing, positioning the file-pointer at the end. Mode \const{update} opens the file for writing, positioning the file-pointer at the beginning of the file without truncating the file. See also stream_position/3. \arg{Stream} is either a variable, in which case it is bound to an integer identifying the stream, or an atom, in which case this atom will be the stream identifier. The \arg{Options} list can contain the following options: \begin{description} \termitem{type}{Type} Using type \const{text} (default), Prolog will write a text-file in an operating-system compatible way. Using type \const{binary} the bytes will be read or written without any translation. Note there is no difference between the two on Unix systems. \termitem{alias}{Atom} Gives the stream a name. The following two calls are identical, but only the latter is allowed in ISO Prolog. \begin{code} ?- open(foo, read, in, []). ?- open(foo, read, S, [alias(in)]). \end{code} \termitem{eof_action}{Action} Defines what happens if the end of the input stream is reached. Action \const{eof_code} makes get0/1 and friends return -1 and read/1 and friends return the atom \const{end_of_file}. Repetitive reading keeps yielding the same result. Action \const{error} is like \const{eof_code}, but repetitive reading will raise an error. With action \const{reset}, Prolog will examine the file again and return more data if the file has grown. \termitem{buffer}{Buffering} Defines output buffering. The atom \const{fullf} (default) defines full buffering, \const{line} buffering by line, and \const{false} implies the stream is fully unbuffered. Smaller buffering is useful if another process or the user is waiting for the output as it is being produced. See also flush/0 and flush_output/1. This option is not an ISO option. \termitem{close_on_abort}{Bool} If \const{true} (default), the stream is closed on an abort (see abort/0). If \const{false}, the stream is not closed. If it is an output stream, it will be flushed however. Useful for logfiles and if the stream is associated to a process (using the \functor{pipe}{1} construct). \end{description} The option \const{reposition} is not supported in SWI-Prolog. All streams connected to a file may be repositioned. \predicate{open}{3}{+SrcDest, +Mode, ?Stream} Equivalent to open/4 with an empty option-list. \predicate{open_null_stream}{1}{?Stream} Open a stream that produces no output. All counting functions are enabled on such a stream. An attempt to read from a null-stream will immediately signal end-of-file. Similar to Unix \file{/dev/null}. \arg{Stream} can be an atom, giving the null-stream an alias name. \predicate{close}{1}{+Stream} Close the specified stream. If \arg{Stream} is not open an error message is displayed. If the closed stream is the current input or output stream the terminal is made the current input or output. \predicate{current_stream}{3}{?File, ?Mode, ?Stream} Is true if a stream with file specification \arg{File}, mode \arg{Mode} and stream identifier \arg{Stream} is open. The reserved streams \const{user} and \const{user_error} are not generated by this predicate. If a stream has been opened with mode \const{append} this predicate will generate mode \const{write}. \predicate{stream_position}{3}{+Stream, -Old, +New} Unify the position parameters of \arg{Stream} with \arg{Old} and set them to \arg{New}. A position is represented by the following term: \begin{code} '$stream_position'(CharNo, LineNo, LinePos). \end{code} It is only possible to change the position parameters if the stream is connected to a disk file. If the position is changed, the \arg{CharNo} field determines the new position in the file. The \arg{LineNo} and \arg{LinePos} are copied in the stream administration. \end{description} \subsection{Switching Between Implicit and Explicit I/O} The predicates below can be used for switching between the implicit- and the explicit stream based I/O predicates. \begin{description} \predicate{set_input}{1}{+Stream} Set the current input stream to become \arg{Stream}. Thus, open(file, read, Stream), set_input(Stream) is equivalent to see(file). \predicate{set_output}{1}{+Stream} Set the current output stream to become \arg{Stream}. \predicate{current_input}{1}{-Stream} Get the current input stream. Useful to get access to the status predicates associated with streams. \predicate{current_output}{1}{-Stream} Get the current output stream. \predicate{dup_stream}{2}{+From, +To} Duplicate the underlying data from stream \arg{From} to stream{To}, so actions performed on either stream have the same effect. The primary goal of this predicate is to facilitate redirection of the user interaction to allow for `interactor' windows. For example, the following code will redirect output to \const{user_output} and \const{user_error} to an XPCE text window: \begin{code} ..., pce_open(Window, append, Fd), dup_stream(user_output, Fd), dup_stream(user_error, Fd), \end{code} The old status of a stream can be stored by duplicating to a null-stream as obtained using open_null_stream/1. This predicate is SWI-Prolog specific. \end{description} \section{Status of Input and Output Streams} \begin{description} \predicate{wait_for_input}{3}{+ListOfStreams, -ReadyList, +TimeOut} Wait for input on one of the streams in \arg{ListOfStreams} and return a list of streams on which input is available in \arg{ReadyList}. wait_for_input/3 waits for at most \arg{TimeOut} seconds. \arg{Timeout} may be specified as a floating point number to specify fractions of a second. If \arg{Timeout} equals 0, wait_for_input/3 waits indefinitely. This predicate can be used to implement timeout while reading and to handle input from multiple sources. The following example will wait for input from the user and an explicitly opened second terminal. On return, \arg{Inputs} may hold \const{user} or \arg{P4} or both. \begin{code} ?- open('/dev/ttyp4', read, P4), wait_for_input([user, P4], Inputs, 0). \end{code} \predicate{character_count}{2}{+Stream, -Count} Unify \arg{Count} with the current character index. For input streams this is the number of characters read since the open, for output streams this is the number of characters written. Counting starts at 0. \predicate{line_count}{2}{+Stream, -Count} Unify \arg{Count} with the number of lines read or written. Counting starts at 1. \predicate{line_position}{2}{+Stream, -Count} Unify \arg{Count} with the position on the current line. Note that this assumes the position is 0 after the open. Tabs are assumed to be defined on each 8-th character and backspaces are assumed to reduce the count by one, provided it is positive. \predicate{fileerrors}{2}{-Old, +New} Define error behaviour on errors when opening a file for reading or writing. Valid values are the atoms \const{on} (default) and \const{off}. First \arg{Old} is unified with the current value. Then the new value is set to \arg{New}.% \footnote{Note that Edinburgh Prolog defines fileerrors/0 and nofileerrors/0. As this does not allow you to switch back to the old mode I think this definition is better.} \end{description} \section{Primitive Character Input and Output} \begin{description} \predicate{nl}{0}{} Write a newline character to the current output stream. On Unix systems nl/0 is equivalent to \exam{put(10)}. \predicate{nl}{1}{+Stream} Write a newline to \arg{Stream}. \predicate{put}{1}{+Char} Write \arg{Char} to the current output stream, \arg{Char} is either an integer-expression evaluating to an ASCII value ($0 \leq \arg{Char} \leq 255$) or an atom of one character. \predicate{put}{2}{+Stream, +Char} Write \arg{Char} to \arg{Stream}. \predicate{tab}{1}{+Amount} Writes \arg{Amount} spaces on the current output stream. \arg{Amount} should be an expression that evaluates to a positive integer (see \secref{arith}). \predicate{tab}{2}{+Stream, +Amount} Writes \arg{Amount} spaces to \arg{Stream}. \predicate{flush}{0}{} Flush pending output on current output stream. flush/0 is automatically generated by read/1 and derivatives if the current input stream is \const{user} and the cursor is not at the left margin. \predicate{flush_output}{1}{+Stream} Flush output on the specified stream. The stream must be open for writing. \predicate{ttyflush}{0}{} Flush pending output on stream \arg{user}. See also flush/0. \predicate{get0}{1}{-Char} Read the current input stream and unify the next character with \arg{Char}. \arg{Char} is unified with -1 on end of file. \predicate{get0}{2}{+Stream, -Char} Read the next character from \arg{Stream}. \predicate{get}{1}{-Char} Read the current input stream and unify the next non-blank character with \arg{Char}. \arg{Char} is unified with -1 on end of file. \predicate{get}{2}{+Stream, -Char} Read the next non-blank character from \arg{Stream}. \predicate{peek_byte}{1}{-Char} Reads the next input character like get0/1, but does not remove it from the input stream. This predicate is ISO compliant. \predicate{peek_byte}{2}{+Stream, -Char} Reads the next input character like get0/2, but does not remove it from the stream. This predicate is ISO compliant. \predicate{skip}{1}{+Char} Read the input until \arg{Char} or the end of the file is encountered. A subsequent call to get0/1 will read the first character after \arg{Char}. \predicate{skip}{2}{+Stream, +Char} Skip input (as skip/1) on \arg{Stream}. \predicate{get_single_char}{1}{-Char} Get a single character from input stream `user' (regardless of the current input stream). Unlike get0/1 this predicate does not wait for a return. The character is not echoed to the user's terminal. This predicate is meant for keyboard menu selection etc.. If SWI-Prolog was started with the \cmdlineoption{-tty} option this predicate reads an entire line of input and returns the first non-blank character on this line, or the ASCII code of the newline (10) if the entire line consisted of blank characters. \predicate{at_end_of_stream}{0}{} Succeeds after the last character of the current input stream has been read. Also succeeds if there is no valid current input stream. \predicate{at_end_of_stream}{1}{+Stream} Succeeds after the last character of the named stream is read, or \arg{Stream} is not a valid input stream. \end{description} \section{Term Reading and Writing} This section describes the basic term reading and writing predicates. The predicates term_to_atom/2 and atom_to_term/3 provide means for translating atoms and strings to terms. The predicates format/[1,2] and writef/2 provide formatted output. There are two ways to manipulate the output format. The predicate print/[1,2] may be programmed using portray/1. The format of floating point numbers may be manipulated using the feature (see feature/2) \const{float_format}. Reading is sensitive to the feature \const{character_escapes}, which controls the interpretation of the \chr{\} character in quoted atoms and strings. \begin{description} \predicate{write_term}{2}{+Term, +Options} The predicate write_term/2 is the generic form of all Prolog term-write predicates. Valid options are: \begin{description} \termitem{quoted}{\const{true} or \const{false}} If \const{true}, atoms and functors that needs quotes will be quoted. The default is \const{false}. \termitem{ignore_ops}{\const{true} or \const{false}} If \const{true}, the generic term-representation (<functor>(<args> \ldots)) will be used for all terms, Otherwise (default), operators, list-notation and \verb${}$/1 will be written using their special syntax. \termitem{numbervars}{\const{true} or \const{false}} If \const{true}, terms of the format \verb|$VAR(N)|, where <N> is a positive integer, will be written as a variable name. The default is \const{false}. \termitem{portray}{\const{true} or \const{false}} If \const{true}, the hook portray/1 is called before printing a term that is not a variable. If portray/1 succeeds, the term is considered printed. See also print/1. The default is \const{false}. This option is an extension to the ISO write_term options. \end{description} \predicate{write_term}{3}{+Stream, +Term, +Options} As write_term/2, but output is sent to \arg{Stream} rather than the current output. \predicate{write_canonical}{1}{+Term} Write \arg{Term} on the current output stream using standard parenthesised prefix notation (i.e. ignoring operator declarations). Atoms that need quotes are quoted. Terms written with this predicate can always be read back, regardless of current operator declarations. Equivalent to write_term/2 using the options \const{ignore_ops} and \const{quoted}. \predicate{write_canonical}{2}{+Stream, +Term} Write \arg{Term} in canonical form on \arg{Stream}. \predicate{write}{1}{+Term} Write \arg{Term} to the current output, using brackets and operators where appropriate. See feature/2 for controlling floating point output format. \predicate{write}{2}{+Stream, +Term} Write \arg{Term} to \arg{Stream}. \predicate{writeq}{1}{+Term} Write \arg{Term} to the current output, using brackets and operators where appropriate. Atoms that need quotes are quoted. Terms written with this predicate can be read back with read/1 provided the currently active operator declarations are identical. \predicate{writeq}{2}{+Stream, +Term} Write \arg{Term} to \arg{Stream}, inserting quotes. \predicate{print}{1}{+Term} Prints \arg{Term} on the current output stream similar to write/1, but for each (sub)term of \arg{Term} first the dynamic predicate portray/1 is called. If this predicate succeeds \arg{print} assumes the (sub)term has been written. This allows for user defined term writing. \predicate{print}{2}{+Stream, +Term} Print \arg{Term} to \arg{Stream}. \predicate{portray}{1}{+Term} A dynamic predicate, which can be defined by the user to change the behaviour of print/1 on (sub)terms. For each subterm encountered that is not a variable print/1 first calls portray/1 using the term as argument. For lists only the list as a whole is given to portray/1. If portray succeeds print/1 assumes the term has been written. \predicate{read}{1}{-Term} Read the next Prolog term from the current input stream and unify it with \arg{Term}. On a syntax error read/1 displays an error message, attempts to skip the erroneous term and fails. On reaching end-of-file \arg{Term} is unified with the atom \const{end_of_file}. \predicate{read}{2}{+Stream, -Term} Read \arg{Term} from \arg{Stream}. \predicate{read_clause}{1}{-Term} Equivalent to read/1, but warns the user for variables only occurring once in a term (singleton variables) which do not start with an underscore if \exam{style_check(singleton)} is active (default). Used to read Prolog source files (see consult/1). New code should use read_term/2 with the option \exam{singletons(warning)}. \predicate{read_clause}{2}{+Stream, -Term} Read a clause from \arg{Stream}. See read_clause/1. \predicate{read_variables}{2}{-Term, -Bindings} Similar to read/1, but \arg{Bindings} is unified with a list of `$\arg{Name} = \arg{Var}$' tuples, thus providing access to the actual variable names. New code should use read_term/2 using the option \exam{variables(X)}. \predicate{read_variables}{3}{+Stream, -Term, -Bindings} Read, returning term and bindings from \arg{Stream}. See read_variables/2. \predicate{read_term}{2}{-Term, +Options} Read a term from the current input stream and unify the term with \arg{Term}. The reading is controlled by options from the list of \arg{Options}. If this list is empty, the behaviour is the same as for read/1. The options are upward compatible to Quintus Prolog. The argument order is according to the ISO standard. Options: \begin{description} \termitem{syntax_errors}{atom or variable} Define the behaviour for when a syntax error occurs. The possible values \begin{description} \termitem{fail}{} Default behaviour. The error is reported as a warning and the predicate fails. \termitem{quiet}{} Quietly fails if a syntax error has occurred. \termitem{\arg{Variable}}{} If no error occurs, the variable is unified with \const{none}, otherwise \arg{Variable} is unified with a term of the form \begin{code} '$stream_position'(CharNo, LineNo, LinePos):Message \end{code} This behaviour is a SWI-Prolog extension. \end{description} \termitem{variable_names}{Vars} Unify \arg{Vars} with a list of `\arg{Name} = \arg{Var}', where \arg{Name} is an atom describing the variable name and \arg{Var} is a variable that shares with the corresponding variable in \arg{Term}. \termitem{singletons}{Vars} As \const{variable_names}, but only reports the variables occurring only once in the \arg{Term} read. Variables starting with an underscore (`\chr{_}') are not included in this list. \termitem{term_position}{Pos} Unifies \arg{Pos} with the starting position of the term read. \arg{Pos} if of the same format as use by stream_position/3. \termitem{subterm_positions}{TermPos} Describes the detailed layout of the term. The formats for the various types of terms if given below. All positions are character positions. If the input is related to a normal stream, these positions are relative to the start of the input, when reading from the terminal, they are relative to the start of the term. \begin{description} \definition{\arg{From}-\arg{To}} Used for primitive types (atoms, numbers, variables). \termitem{string_position}{\arg{From}, \arg{To}} Used to indicate the position of a string enclosed in double quotes (\chr{"}). \termitem{brace_term_position}{\arg{From}, \arg{To}, \arg{Arg}} Term of the form \exam{\{\ldots \}}, as used in DCG rules. \arg{Arg} describes the argument. \termitem{list_position}{\arg{From}, \arg{To}, \arg{Elms}, \arg{Tail}} A list. \arg{Elms} describes the positions of the elements. If the list specifies the tail as \mbox{\chr{|}<TailTerm>}, \arg{Tail} is unified with the term-position of the tail, otherwise with the atom \const{none}. \termitem{term_position}{\arg{From}, \arg{To}, \arg{FFrom}, \arg{FTo}, \arg{SubPos}} Used for a compound term not matching one of the above. \arg{FFrom} and \arg{FTo} describe the position of the functor. \arg{SubPos} is a list, each element of which describes the term-position of the corresponding subterm. \end{description} \end{description} \predicate{read_term}{3}{+Stream, -Term, +Options} Read term with options from \arg{Stream}. See read_term/2. \predicate{read_history}{6}{+Show, +Help, +Special, +Prompt, -Term, -Bindings} Similar to read_variables/2, but allows for history substitutions. read_history/6 is used by the top level to read the user's actions. \arg{Show} is the command the user should type to show the saved events. \arg{Help} is the command to get an overview of the capabilities. \arg{Special} is a list of commands that are not saved in the history. \arg{Prompt} is the first prompt given. Continuation prompts for more lines are determined by prompt/2. A \const{\%w} in the prompt is substituted by the event number. See \secref{history} for available substitutions. SWI-Prolog calls read_history/6 as follows: \begin{code} read_history(h, '!h', [trace], '%w ?- ', Goal, Bindings) \end{code} \predicate{prompt}{2}{-Old, +New} Set prompt associated with read/1 and its derivatives. \arg{Old} is first unified with the current prompt. On success the prompt will be set to \arg{New} if this is an atom. Otherwise an error message is displayed. A prompt is printed if one of the read predicates is called and the cursor is at the left margin. It is also printed whenever a newline is given and the term has not been terminated. Prompts are only printed when the current input stream is \arg{user}. \predicate{prompt1}{1}{+Prompt} Sets the prompt for the next line to be read. Continuation lines will be read using the prompt defined by prompt/2. \end{description} \section{Analysing and Constructing Terms} \begin{description} \predicate{functor}{3}{?Term, ?Functor, ?Arity} Succeeds if \arg{Term} is a term with functor \arg{Functor} and arity \arg{Arity}. If \arg{Term} is a variable it is unified with a new term holding only variables. functor/3 silently fails on instantiation faults% \footnote{In version 1.2 instantiation faults led to error messages. The new version can be used to do type testing without the need to catch illegal instantiations first.} If \arg{Term} is an atom or number, \arg{Functor} will be unified with \arg{Term} and arity will be unified with the integer 0 (zero). \predicate{arg}{3}{?Arg, ?Term, ?Value} \arg{Term} should be instantiated to a term, \arg{Arg} to an integer between 1 and the arity of \arg{Term}. \arg{Value} is unified with the \arg{Arg}-th argument of \arg{Term}. \arg{Arg} may also be unbound. In this case \arg{Value} will be unified with the successive arguments of the term. On successful unification, \arg{Arg} is unified with the argument number. Backtracking yields alternative solutions.% \footnote{The instantiation pattern (-, +, ?) is an extension to `standard' Prolog.} The predicate arg/3 fails silently if $\arg{Arg} = 0$ or $\arg{Arg} > \mbox{\em arity}$ and raises the exception \errorterm{domain_error}{not_less_then_zero, \arg{Arg}} if $\arg{Arg} < \predicate{setarg}{3}{+Arg, +Term, +Value} Extra-logical predicate. Assigns the \arg{Arg}-th argument of the compound term \arg{Term} with the given \arg{Value}. The assignment is undone if backtracking brings the state back into a position before the setarg/3 call. This predicate may be used for destructive assignment to terms, using them as and extra-logical storage bin. \infixop{=..}{?Term}{?List} \arg{List} is a list which head is the functor of \arg{Term} and the remaining arguments are the arguments of the term. Each of the arguments may be a variable, but not both. This predicate is called `Univ'. Examples: \begin{code} ?- foo(hello, X) =.. List. List = [foo, hello, X] ?- Term =.. [baz, foo(1)] Term = baz(foo(1)) \end{code} \predicate{numbervars}{4}{+Term, +Functor, +Start, -End} Unify the free variables of \arg{Term} with a term constructed from the atom \arg{Functor} with one argument. The argument is the number of the variable. Counting starts at \arg{Start}. \arg{End} is unified with the number that should be given to the next variable. Example: \begin{code} ?- numbervars(foo(A, B, A), this_is_a_variable, 0, End). A = this_is_a_variable(0) B = this_is_a_variable(1) End = 2 \end{code} In Edinburgh Prolog the second argument is missing. It is fixed to be \const{\$VAR}. \predicate{free_variables}{2}{+Term, -List} Unify \arg{List} with a list of variables, each sharing with a unique variable of \arg{Term}. For example: \begin{code} ?- free_variables(a(X, b(Y, X), Z), L). L = [G367, G366, G371] X = G367 Y = G366 Z = G371 \end{code} \predicate{copy_term}{2}{+In, -Out} Make a copy of term \arg{In} and unify the result with \arg{Out}. Ground parts of \arg{In} are shared by \arg{Out}. Provided \arg{In} and \arg{Out} have no sharing variables before this call they will have no sharing variables afterwards. copy_term/2 is semantically equivalent \begin{code} copy_term(In, Out) :- recorda(copy_key, In, Ref), recorded(copy_key, Out, Ref), erase(Ref). \end{code} \end{description} \section{Analysing and Constructing Atoms} These predicates convert between Prolog constants and lists of ASCII values. The predicates atom_chars/2, number_chars/2 and name/2 behave the same when converting from a constant to a list of ASCII values. When converting the other way around, atom_chars/2 will generate an atom, number_chars will generate a number or fail and name/2 will return a number if possible and an atom otherwise. \begin{description} \predicate{atom_chars}{2}{?Atom, ?String} Convert between an atom and a list of ASCII values. If \arg{Atom} is instantiated, if will be translated into a list of ASCII values and the result is unified with \arg{String}. If \arg{Atom} is unbound and \arg{String} is a list of ASCII values, it will \arg{Atom} will be unified with an atom constructed from this list. \predicate{atom_char}{2}{?Atom, ?ASCII} Convert between character and ASCII value for a single character. \predicate{number_chars}{2}{?Number, ?String} Similar to atom_chars/2, but converts between a number and its representation as a list of ASCII values. Fails silently if \arg{Number} is unbound and \arg{String} does not describe a number. \predicate{name}{2}{?AtomOrInt, ?String} \arg{String} is a list of ASCII values describing \arg{Atom}. Each of the arguments may be a variable, but not both. When \arg{String} is bound to an ASCII value list describing an integer and \arg{Atom} is a variable \arg{Atom} will be unified with the integer value described by \arg{String} (e.g. `\exam{name(N, "300"), 400 is N + 100}' succeeds). \predicate{int_to_atom}{3}{+Int, +Base, -Atom} Convert \arg{Int} to an {\sc ascii} representation using base \arg{Base} and unify the result with \arg{Atom}. If $\arg{Base} \not= 10$ the base will be prepended to \arg{Atom}. $\arg{Base} = 0$ will try to interpret \arg{Int} as an ASCII value and return \const{0'}<c>. Otherwise $2 \leq \arg{Base} \leq 36$. Some examples are given below. \begin{center}\begin{tabular}{lcl} int_to_atom(45, 2, A) & $\longrightarrow$ & $A = 2'101101$ \\ int_to_atom(97, 0, A) & $\longrightarrow$ & $A = 0'a$ \\ int_to_atom(56, 10, A) & $\longrightarrow$ & $A = 56$ \\ \end{tabular}\end{center} \predicate{int_to_atom}{2}{+Int, -Atom} Equivalent to \exam{int_to_atom(Int, 10, Atom)}. \predicate{term_to_atom}{2}{?Term, ?Atom} Succeeds if \arg{Atom} describes a term that unifies with \arg{Term}. When \arg{Atom} is instantiated \arg{Atom} is converted and then unified with \arg{Term}. Otherwise \arg{Term} is ``written'' on \arg{Atom} using write/1. \predicate{atom_to_term}{3}{+Atom, -Term, -Bindings} Use \arg{Atom} as input to read_variables/2 and return the read term in \arg{Term} and the variable bindings in \arg{Bindings}. \arg{Bindings} is a list of $\arg{Name} = \arg{Var}$ couples, thus providing access to the actual variable names. See also read_variables/2. \predicate{concat}{3}{?Atom1, ?Atom2, ?Atom3} \arg{Atom3} forms the concatenation of \arg{Atom1} and \arg{Atom2}. At least two of the arguments must be instantiated to atoms, integers or floating point numbers. \predicate{concat_atom}{2}{+List, -Atom} \arg{List} is a list of atoms, integers or floating point numbers. Succeeds if \arg{Atom} can be unified with the concatenated elements of \arg{List}. If \arg{List} has exactly 2 elements it is equivalent to concat/3, allowing for variables in the list. \predicate{concat_atom}{3}{+List, +Separator, -Atom} Creates an atom just like concat_atom/2, but inserts \arg{Separator} between each pair of atoms. For example: \begin{code} ?- concat_atom([gnu, gnat], ', ', A). A = 'gnu, gnat' \end{code} \predicate{atom_length}{2}{+Atom, -Length} Succeeds if \arg{Atom} is an atom of \arg{Length} characters long. This predicate also works for integers and floats, expressing the number of characters output when given to write/1. \predicate{atom_prefix}{2}{+Atom, +Prefix} Succeeds if \arg{Atom} starts with the characters from \arg{Prefix}. Its behaviour is equivalent to \exam{?- concat(\arg{Prefix}, _, \arg{Atom})}, but avoids the construction of an atom for the `remainder'. \end{description} \section{Representing Text in Strings} \label{sec:strings} SWI-Prolog supports the data type \arg{string}. Strings are a time and space efficient mechanism to handle text in Prolog. Atoms are under some circumstances not suitable because garbage collection on them is next to impossible (Although it is possible: BIM_prolog does it). Representing text as a list of ASCII values is, from the logical point of view, the cleanest solution. It however has two drawbacks: 1) they cannot be distinguished from a list of (small) integers; and 2) they consume (in SWI-Prolog) 12 bytes for each character stored. Within strings each character only requires 1 byte storage. Strings live on the global stack and their storage is thus reclaimed on backtracking. Garbage collection can easily deal with strings. The ISO standard proposes \exam{" \ldots "} is transformed into a string object by read/1 and derivatives. This poses problems as in the old convention \exam{" \ldots "} is transformed into a list of {\sc ascii} characters. For this reason the style check option `\const{string}' is available (see style_check/1). The set of predicates associated with strings is incomplete and tentative. Names and definitions might change in the future to confirm to the emerging standard. \begin{description} \predicate{string_to_atom}{2}{?String, ?Atom} Logical conversion between a string and an atom. At least one of the two arguments must be instantiated. \arg{Atom} can also be an integer or floating point number. \predicate{string_to_list}{2}{?String, ?List} Logical conversion between a string and a list of ASCII characters. At least one of the two arguments must be instantiated. \predicate{string_length}{2}{+String, -Length} Unify \arg{Length} with the number of characters in \arg{String}. This predicate is functionally equivalent to atom_length/2 and also accepts atoms, integers and floats as its first argument. \predicate{string_concat}{3}{?String1, ?String2, ?String3} Similar to concat/3, but the unbound argument will be unified with a string object rather than an atom. Also, if both \arg{String1} and \arg{String2} are unbound and \arg{String3} is bound to text, it breaks \arg{String3}, unifying the start with \arg{String1} and the end with \arg{String2} as append does with lists. Note that this is not particularly fast on long strings as for each redo the system has to create two entirely new strings, while the list equivalent only creates a single new list-cell and moves some pointers around. \predicate{substring}{4}{+String, +Start, +Length, -Sub} Create a substring of \arg{String} that starts at character \arg{Start} (1 base) and has \arg{Length} characters. Unify this substring with \arg{Sub}.% \footnote{Future versions probably will provide a more logical variant of this predicate.} \end{description} \section{Operators} \begin{description} \predicate{op}{3}{+Precedence, +Type, +Name} Declare \arg{Name} to be an operator of type \arg{Type} with precedence \arg{Precedence}. \arg{Name} can also be a list of names, in which case all elements of the list are declared to be identical operators. \arg{Precedence} is an integer between 0 and 1200. Precedence 0 removes the declaration. \arg{Type} is one of: \const{xf}, \const{yf}, \const{xfx}, \const{xfy}, \const{yfx}, \const{yfy}, \const{fy} or \const{fx}. The `\chr{f}' indicates the position of the functor, while \chr{x} and \chr{y} indicate the position of the arguments. `\chr{y}' should be interpreted as ``on this position a term with precedence lower or equal to the precedence of the functor should occur''. For `\chr{x}' the precedence of the argument must be strictly lower. The precedence of a term is 0, unless its principal functor is an operator, in which case the precedence is the precedence of this operator. A term enclosed in brackets \exam{(\ldots)} has precedence 0. The predefined operators are shown in \tabref{operators}. Note that all operators can be redefined by the user. \begin{table} \begin{center} \begin{tabular}{|r|D{f}{f}{-1}|p{4in}|} \hline 1200 & xfx & \op{-->}, \op{:-} \\ 1200 & fx & \op{:-}, \op{?-} \\ 1150 & fx & \op{dynamic}, \op{multifile}, \op{module_transparent}, \op{discontiguous}, \op{volatile}, \op{initialization}\\ 1100 & xfy & \op{;}, \op{|} \\ 1050 & xfy & \op{->} \\ 1000 & xfy & \op{,} \\ 954 & xfy & \op{\} \\ 900 & fy & \op{\+}, \op{not} \\ 900 & fx & \op{~} \\ 700 & xfx & \op{<}, \op{=}, \op{=..}, \op{=@=}, \op{=:=}, \op{=<}, \op{==}, \op{=\=}, \op{>}, \op{>=}, \op{@<}, \op{@=<}, \op{@>}, \op{@>=}, \op{\=}, \op{\==}, \op{is} \\ 600 & xfy & \op{:} \\ 500 & yfx & \op{+}, \op{-}, \op{/\}, \op{\/}, \op{xor} \\ 500 & fx & \op{+}, \op{-}, \op{?}, \op{\} \\ 400 & yfx & \op{*}, \op{/}, \op{//}, \op{<<}, \op{>>}, \op{mod}, \op{rem} \\ 200 & xfx & \op{**} \\ 200 & xfy & \op{^} \\ \hline \end{tabular} \end{center} \caption{System operators} \label{tab:operators} \end{table} \predicate{current_op}{3}{?Precedence, ?Type, ?Name} Succeeds when \arg{Name} is currently defined as an operator of type \arg{Type} with precedence \arg{Precedence}. See also op/3. \end{description} \section{Arithmetic} \label{sec:arith} Arithmetic can be divided into some special purpose integer predicates and a series of general predicates for floating point and integer arithmetic as appropriate. The integer predicates are as ``logical'' as possible. Their usage is recommended whenever applicable, resulting in faster and more ``logical'' programs. The general arithmetic predicates are optionally compiled now (see please/3 and the \cmdlineoption{-O} command line option). Compiled arithmetic reduces global stack requirements and improves performance. Unfortunately compiled arithmetic cannot be traced, which is why it is optional. The general arithmetic predicates all handle \arg{expressions}. An expression is either a simple number or a \arg{function}. The arguments of a function are expressions. The functions are described in \secref{functions}. \begin{description} \predicate{between}{3}{+Low, +High, ?Value} \arg{Low} and \arg{High} are integers, $\arg{High} \geq \arg{Low}$. If \arg{Value} is an integer, $\arg{Low} \leq \arg{Value} \leq \arg{High}$. When \arg{Value} is a variable it is successively bound to all integers between \arg{Low} and \arg{High}. \predicate{succ}{2}{?Int1, ?Int2} Succeeds if $\arg{Int2} = \arg{Int1} + 1$. At least one of the arguments must be instantiated to an integer. \predicate{plus}{3}{?Int1, ?Int2, ?Int3} Succeeds if $\arg{Int3} = \arg{Int1} + \arg{Int2}$. At least two of the three arguments must be instantiated to integers. \infixop{>}{+Expr1}{+Expr2} Succeeds when expression \arg{Expr1} evaluates to a larger number than \arg{Expr2}. \infixop{<}{+Expr1}{+Expr2} Succeeds when expression \arg{Expr1} evaluates to a smaller number than \arg{Expr2}. \infixop{=<}{+Expr1}{+Expr2} Succeeds when expression \arg{Expr1} evaluates to a smaller or equal number to \arg{Expr2}. \infixop{>=}{+Expr1}{+Expr2} Succeeds when expression \arg{Expr1} evaluates to a larger or equal number to \arg{Expr2}. \infixop{=\=}{+Expr1}{+Expr2} Succeeds when expression \arg{Expr1} evaluates to a number non-equal to \arg{Expr2}. \infixop{=:=}{+Expr1}{+Expr2} Succeeds when expression \arg{Expr1} evaluates to a number equal to \arg{ Expr2}. \infixop{is}{-Number}{+Expr} Succeeds when \arg{Number} has successfully been unified with the number \arg{Expr} evaluates to. If \arg{Expr} evaluates to a float that can be represented using an integer (i.e.\ the value is integer and within the range that can be described by Prolog's integer representation), \arg{ Expr} is unified with the integer value. Note that normally, is/2 will be used with unbound left operand. If equality is to be tested, =:=/2 should be used. For example: \begin{center}\begin{tabular}{lp{2.5in}} \exam{?- 1.0 is sin({pi}/2).} & Fails!. sin({pi}/2) evaluates to 1.0, but is/2 will represent this as the integer 1, after which unify will fail. \\ \exam{?- 1.0 is float(sin({pi}/2)).} & Succeeds, as the float/1 function forces the result to be float. \\ \exam{?- 1.0 =:= sin({pi}/2).} & Succeeds as expected. \end{tabular}\end{center} \end{description} \section{Arithmetic Functions} \label{sec:functions} Arithmetic functions are terms which are evaluated by the arithmetic predicates described above. SWI-Prolog tries to hide the difference between integer arithmetic and floating point arithmetic from the Prolog user. Arithmetic is done as integer arithmetic as long as possible and converted to floating point arithmetic whenever one of the arguments or the combination of them requires it. If a function returns a floating point value which is whole it is automatically transformed into an integer. There are three types of arguments to functions: \begin{center}\begin{tabular}{lp{4in}} \arg{Expr} & Arbitrary expression, returning either a floating point value or an integer. \\ \arg{IntExpr} & Arbitrary expression that should evaluate into an integer. \\ \arg{Int} & An integer. \end{tabular}\end{center} In case integer addition, subtraction and multiplication would lead to an integer overflow the operands are automatically converted to floating point numbers. The floating point functions (sin/1, exp/1, etc.) form a direct interface to the corresponding C library functions used to compile SWI-Prolog. Please refer to the C library documentation for details on precision, error handling, etc. \begin{description} \prefixop{-}{+Expr} $\arg{Result} = -\arg{Expr}$ \infixop{+}{+Expr1}{+Expr2} $\arg{Result} = \arg{Expr1} + \arg{Expr2}$ \infixop{-}{+Expr1}{+Expr2} $\arg{Result} = \arg{Expr1} - \arg{Expr2}$ \infixop{*}{+Expr1}{+Expr2} $\arg{Result} = \arg{Expr1} \times \arg{Expr2}$ \infixop{/}{+Expr1}{+Expr2} $\arg{Result} = \frac{\arg{Expr1}}{\arg{Expr2}}$ \infixop{mod}{+IntExpr1}{+IntExpr2} $\arg{Result} = \mod{\arg{Expr1}}{\arg{Expr2}}$ (remainder of division). \infixop{rem}{+IntExpr1}{+IntExpr2} $\arg{Result} = \rem{\arg{Expr1}}{\arg{Expr2}}$ (remainder of division). \infixop{//}{+IntExpr1}{+IntExpr2} $\arg{Result} = \arg{Expr1} \div \arg{Expr2}$ (integer division). \predicate{abs}{1}{+Expr} Evaluate \arg{Expr} and return the absolute value of it. \predicate{sign}{1}{+Expr} Evaluate to -1 if $\arg{Expr} < 0$, 1 if $\arg{Expr} > 0$ and 0 if $\arg{Expr} = 0$. \predicate{max}{2}{+Expr1, +Expr2} Evaluates to the largest of both \arg{Expr1} and \arg{Expr2}. \predicate{min}{2}{+Expr1, +Expr2} Evaluates to the smallest of both \arg{Expr1} and \arg{Expr2}. \predicate{.}{2}{+Int, []} A list of one element evaluates to the element. This implies \exam{"a"} evaluates to the ASCII value of the letter `a' (97). This option is available for compatibility only. It will not work if `\exam{style_check(+string)}' is active as \exam{"a"} will then be transformed into a string object. The recommended way to specify the ASCII value of the letter `a' is \exam{0'a}. \predicate{random}{1}{+Int} Evaluates to a random integer \arg{i} for which $0 \leq i < \arg{Int}$. The seed of this random generator is determined by the system clock when SWI-Prolog was started. \predicate{round}{1}{+Expr} Evaluates \arg{Expr} and rounds the result to the nearest integer. \predicate{integer}{1}{+Expr} Same as round/1 (backward compatibility). \predicate{float}{1}{+Expr} Translate the result to a floating point number. Normally, Prolog will use integers whenever possible. When used around the 2nd argument of is/2, the result will be returned as a floating point number. In other contexts, the operation has no effect. \predicate{float_fractional_part}{1}{+Expr} Fractional part of a floating-point number. Negative if \arg{Expr} is negative, 0 if \arg{Expr} is integer. \predicate{float_integer_part}{1}{+Expr} Integer part of floating-point number. Negative if \arg{Expr} is negative, \arg{Expr} if \arg{Expr} is integer. \predicate{truncate}{1}{+Expr} Truncate \arg{Expr} to an integer. Same as float_integer_part/1. \predicate{floor}{1}{+Expr} Evaluates \arg{Expr} and returns the largest integer smaller or equal to the result of the evaluation. \predicate{ceiling}{1}{+Expr} Evaluates \arg{Expr} and returns the smallest integer larger or equal to the result of the evaluation. \predicate{ceil}{1}{+Expr} Same as ceiling/1 (backward compatibility). \infixop{>>}{+IntExpr}{+IntExpr} Bitwise shift \arg{IntExpr1} by \arg{IntExpr2} bits to the right. \infixop{<<}{+IntExpr}{+IntExpr} Bitwise shift \arg{IntExpr1} by \arg{IntExpr2} bits to the left. \infixop{\/}{+IntExpr}{+IntExpr} Bitwise `or' \arg{IntExpr1} and \arg{IntExpr2}. \infixop{/\}{+IntExpr}{+IntExpr} Bitwise `and' \arg{IntExpr1} and \arg{IntExpr2}. \infixop{xor}{+IntExpr}{+IntExpr} Bitwise `exclusive or' \arg{IntExpr1} and \arg{IntExpr2}. \prefixop{\}{+IntExpr} Bitwise negation. \predicate{sqrt}{1}{+Expr} $\arg{Result} = \sqrt{\arg{Expr}}$ \predicate{sin}{1}{+Expr} $\arg{Result} = \sin{\arg{Expr}}$. \arg{Expr} is the angle in radians. \predicate{cos}{1}{+Expr} $\arg{Result} = \cos{\arg{Expr}}$. \arg{Expr} is the angle in radians. \predicate{tan}{1}{+Expr} $\arg{Result} = \tan{\arg{Expr}}$. \arg{Expr} is the angle in radians. \predicate{asin}{1}{+Expr} $\arg{Result} = \arcsin{\arg{Expr}}$. \arg{Result} is the angle in radians. \predicate{acos}{1}{+Expr} $\arg{Result} = \arccos{\arg{Expr}}$. \arg{Result} is the angle in radians. \predicate{atan}{1}{+Expr} $\arg{Result} = \arctan{\arg{Expr}}$. \arg{Result} is the angle in radians. \predicate{atan}{2}{+YExpr, +XExpr} $\arg{Result} = \arctan{\frac{\arg{YExpr}}{\arg{XExpr}}}$. \arg{Result} is the angle in radians. The return value is in the range $[-\pi\ldots\pi]$. Used to convert between rectangular and polar coordinate system. \predicate{log}{1}{+Expr} $\arg{Result} = \ln{\arg{Expr}}$ \predicate{log10}{1}{+Expr} $\arg{Result} = \lg{\arg{Expr}}$ \predicate{exp}{1}{+Expr} $\arg{Result} = \pow{e}{\arg{Expr}}$ \infixop{**}{+Expr1}{+Expr2} $\arg{Result} = \pow{\arg{Expr1}}{\arg{Expr2}}$ \infixop{^}{+Expr1}{+Expr2} Same as **/2. (backward compatibility). \predicate{pi}{0}{} Evaluates to the mathematical constant $\pi$ (3.141593). \predicate{e}{0}{} Evaluates to the mathematical constant $e$ (2.718282). \predicate{cputime}{0}{} Evaluates to a floating point number expressing the {\sc cpu} time (in seconds) used by Prolog up till now. See also statistics/2 and time/1. \end{description} \section{Adding Arithmetic Functions} Prolog predicates can be given the role of arithmetic function. The last argument is used to return the result, the arguments before the last are the inputs. Arithmetic functions are added using the predicate arithmetic_function/1, which takes the head as its argument. Arithmetic functions are module sensitive, that is they are only visible from the module in which the function is defined and declared. Global arithmetic functions should be defined and registered from module \const{user}. Global definitions can be overruled locally in modules. The builtin functions described above can be redefined as well. \begin{description} \predicate{arithmetic_function}{1}{+Head} Register a Prolog predicate as an arithmetic function (see is/2, \predref{>}{2}, etc.). The Prolog predicate should have one more argument than specified by \arg{Head}, which it either a term \arg{Name/Arity}, an atom or a complex term. This last argument is an unbound variable at call time and should be instantiated to an integer or floating point number. The other arguments are the parameters. This predicate is module sensitive and will declare the arithmetic function only for the context module, unless declared from module \const{user}. Example: \begin{code} 1 ?- [user]. :- arithmetic_function(mean/2). mean(A, B, C) :- C is (A+B)/2. user compiled, 0.07 sec, 440 bytes. 2 ?- A is mean(4, 5). A = 4.500000 \end{code} \predicate{current_arithmetic_function}{1}{?Head} Successively unifies all arithmetic functions that are visible from the context module with \arg{Head}. \end{description} \section{List Manipulation} \begin{description} \predicate{is_list}{1}{+Term} Succeeds if \arg{Term} is bound to the empty list (\exam{[]}) or a term with functor `\const{.}' and arity~2. \predicate{proper_list}{1}{+Term} Equivalent to is_list/1, but also requires the tail of the list to be a list (recursively). Examples: \begin{code} is_list([x|A]) % true proper_list([x|A]) % false \end{code} \predicate{append}{3}{?List1, ?List2, ?List3} Succeeds when \arg{List3} unifies with the concatenation of \arg{List1} and \arg{List2}. The predicate can be used with any instantiation pattern (even three variables). \predicate{member}{2}{?Elem, ?List} Succeeds when \arg{Elem} can be unified with one of the members of \arg{List}. The predicate can be used with any instantiation pattern. \predicate{memberchk}{2}{?Elem, +List} Equivalent to member/2, but leaves no choice point. \predicate{delete}{3}{+List1, ?Elem, ?List2} Delete all members of \arg{List1} that simultaneously unify with \arg{Elem} and unify the result with \arg{List2}. \predicate{select}{3}{?List1, ?Elem, ?List2} Select an element of \arg{List1} that unifies with \arg{Elem}. \arg{List2} is unified with the list remaining from \arg{List1} after deleting the selected element. Normally used with the instantiation pattern \arg{+List1, -Elem, -List2}, but can also be used to insert an element in a list using \arg{-List1, +Elem, +List2}. \predicate{nth0}{3}{?Index, ?List, ?Elem} Succeeds when the \arg{Index}-th element of \arg{List} unifies with \arg{Elem}. Counting starts at 0. \predicate{nth1}{3}{?Index, ?List, ?Elem} Succeeds when the \arg{Index}-th element of \arg{List} unifies with \arg{Elem}. Counting starts at 1. \predicate{last}{2}{?Elem, ?List} Succeeds if \arg{Elem} unifies with the last element of \arg{List}. \predicate{reverse}{2}{+List1, -List2} Reverse the order of the elements in \arg{List1} and unify the result with the elements of \arg{List2}. \predicate{flatten}{2}{+List1, -List2} Transform \arg{List1}, possibly holding lists as elements into a `flat' list by replacing each list with its elements (recursively). Unify the resulting flat list with \arg{List2}. Example: \begin{code} ?- flatten([a, [b, [c, d], e]], X). X = [a, b, c, d, e] \end{code} \predicate{length}{2}{?List, ?Int} Succeeds if \arg{Int} represents the number of elements of list \arg{List}. Can be used to create a list holding only variables. \predicate{merge}{3}{+List1, +List2, -List3} \arg{List1} and \arg{List2} are lists, sorted to the standard order of terms (see \secref{compare}). \arg{List3} will be unified with an ordered list holding both the elements of \arg{List1} and \arg{List2}. Duplicates are {\bf not} removed. \end{description} \section{Set Manipulation} \begin{description} \predicate{is_set}{1}{+Set} Succeeds if \arg{Set} is a proper list (see proper_list/1) without duplicates. \predicate{list_to_set}{2}{+List, -Set} Unifies \arg{Set} with a list holding the same elements as \arg{List} in the same order. If \arg{list} contains duplicates, only the first is retained. See also sort/2. Example: \begin{code} ?- list_to_set([a,b,a], X) X = [a,b] \end{code} \predicate{intersection}{3}{+Set1, +Set2, -Set3} Succeeds if \arg{Set3} unifies with the intersection of \arg{Set1} and \arg{Set2}. \arg{Set1} and \arg{Set2} are lists without duplicates. They need not be ordered. \predicate{subtract}{3}{+Set, +Delete, -Result} Delete all elements of set `Delete' from `Set' and unify the resulting set with `Result'. \predicate{union}{3}{+Set1, +Set2, -Set3} Succeeds if \arg{Set3} unifies with the union of \arg{Set1} and \arg{Set2}. \arg{Set1} and \arg{Set2} are lists without duplicates. They need not be ordered. \predicate{subset}{2}{+Subset, +Set} Succeeds if all elements of \arg{Subset} are elements of \arg{Set} as well. \predicate{merge_set}{3}{+Set1, +Set2, -Set3} \arg{Set1} and \arg{Set2} are lists without duplicates, sorted to the standard order of terms. \arg{Set3} is unified with an ordered list without duplicates holding the union of the elements of \arg{Set1} and \arg{Set2}. \end{description} \section{Sorting Lists} \begin{description} \predicate{sort}{2}{+List, -Sorted} Succeeds if \arg{Sorted} can be unified with a list holding the elements of \arg{List}, sorted to the standard order of terms (see \secref{compare}). Duplicates are removed. Implemented by translating the input list into a temporary array, calling the C-library function \manref{qsort}{3} using \funcref{PL_compare}{} for comparing the elements, after which the result is translated into the result list. \predicate{msort}{2}{+List, -Sorted} Equivalent to sort/2, but does not remove duplicates. \predicate{keysort}{2}{+List, -Sorted} \arg{List} is a list of \exam{\arg{Key}-\arg{Value}} pairs (e.g.\ terms of the functor `\const{-}' with arity~2). keysort/2 sorts \arg{List} like msort/2, but only compares the keys. Can be used to sort terms not on standard order, but on any criterion that can be expressed on a multi-dimensional scale. Sorting on more than one criterion can be done using terms as keys, putting the first criterion as argument 1, the second as argument 2, etc. The order of multiple elements that have the same \arg{Key} is not changed. \predicate{predsort}{3}{+Pred, +List, -Sorted} Sorts similar to msort/2, but determines the order of two terms by applying \arg{Pred} to pairs of elements from \arg{List} (see apply/2). The predicate should succeed if the first element should be before the second. \end{description} \section{Finding all Solutions to a Goal} \begin{description} \predicate{findall}{3}{+Var, +Goal, -Bag} Creates a list of the instantiations \arg{Var} gets successively on backtracking over \arg{Goal} and unifies the result with \arg{Bag}. Succeeds with an empty list if \arg{Goal} has no solutions. findall/3 is equivalent to bagof/3 with all free variables bound with the existence operator (\op{^}), except that bagof/3 fails when goal has no solutions. \predicate{bagof}{3}{+Var, +Goal, -Bag} Unify \arg{Bag} with the alternatives of \arg{Var}, if \arg{Goal} has free variables besides the one sharing with \arg{Var} bagof will backtrack over the alternatives of these free variables, unifying \arg{Bag} with the corresponding alternatives of \arg{Var}. The construct \exam{+\arg{Var}{^}\arg{Goal}} tells bagof not to bind \arg{Var} in \arg{Goal}. bagof/3 fails if \arg{Goal} has no solutions. The example below illustrates bagof/3 and the \op{^} operator. The variable bindings are printed together on one line to save paper. \begin{code} 2 ?- listing(foo). foo(a, b, c). foo(a, b, d). foo(b, c, e). foo(b, c, f). foo(c, c, g). 3 ?- bagof(C, foo(A, B, C), Cs). A = a, B = b, C = G308, Cs = [c, d] ; A = b, B = c, C = G308, Cs = [e, f] ; A = c, B = c, C = G308, Cs = [g] ; 4 ?- bagof(C, A^foo(A, B, C), Cs). A = G324, B = b, C = G326, Cs = [c, d] ; A = G324, B = c, C = G326, Cs = [e, f, g] ; \end{code} \predicate{setof}{3}{+Var, +Goal, -Set} Equivalent to bagof/3, but sorts the result using sort/2 to get a sorted list of alternatives without duplicates. \end{description} \section{Invoking Predicates on all Members of a List} All the predicates in this section call a predicate on all members of a list or until the predicate called fails. The predicate is called via apply/2, which implies common arguments can be put in front of the arguments obtained from the list(s). For example: \begin{code} ?- maplist(plus(1), [0, 1, 2], X). X = [1, 2, 3] \end{code} we will phrase this as ``\arg{Predicate} is applied on \ldots'' \begin{description} \predicate{checklist}{2}{+Pred, +List} \arg{Pred} is applied successively on each element of \arg{List} until the end of the list or \arg{Pred} fails. In the latter case the checklist/2 fails. \predicate{maplist}{3}{+Pred, ?List1, ?List2} Apply \arg{Pred} on all successive pairs of elements from \arg{List1} and \arg{List2}. Fails if \arg{Pred} can not be applied to a pair. See the example above. \predicate{sublist}{3}{+Pred, +List1, ?List2} Unify \arg{List2} with a list of all elements of \arg{List1} to which \arg{Pred} applies. \end{description} \section{Forall} \begin{description} \predicate{forall}{2}{+Cond, +Action} For all alternative bindings of \arg{Cond} \arg{Action} can be proven. The example verifies that all arithmetic statements in the list \arg{L} are correct. It does not say which is wrong if one proves wrong. \begin{code} ?- forall(member(Result = Formula, [2 = 1 + 1, 4 = 2 * 2]), Result =:= Formula). \end{code} \end{description} \section{Formatted Write} The current version of SWI-Prolog provides two formatted write predicates. The first is writef/[1,2], which is compatible with Edinburgh C-Prolog. The second is format/[1,2], which is compatible with Quintus Prolog. We hope the Prolog community will once define a standard formatted write predicate. If you want performance use format/[1,2] as this predicate is defined in C. Otherwise compatibility reasons might tell you which predicate to use. \subsection{Writef} \begin{description} \predicate{write_ln}{1}{+Term} Equivalent to \exam{write(Term), nl.} \predicate{writef}{1}{+Atom} Equivalent to \exam{writef(Atom, []).} \predicate{writef}{2}{+Format, +Arguments} Formatted write. \arg{Format} is an atom whose characters will be printed. \arg{Format} may contain certain special character sequences which specify certain formatting and substitution actions. \arg{Arguments} then provides all the terms required to be output. Escape sequences to generate a single special character: \begin{center} \begin{tabular}{|l|p{3.5in}|} \hline \fmtseq{\n} & Output a nemline character (see also nl/[0,1]) \\ \fmtseq{\l} & Output a line separator (same as \fmtseq{\n}) \\ \fmtseq{\r} & Output a carriage-return character (ASCII 13) \\ \fmtseq{\t} & Output the ASCII character TAB (9) \\ \fmtseq{\\} & The character \chr{\} is output \\ \fmtseq{\%} & The character \chr{%} is output \\ \fmtseq{\nnn} & where <nnn> is an integer (1-3 digits) the character with ASCII code <nnn> is output (NB : <nnn> is read as \strong{decimal}) \\ \hline \end{tabular} \end{center} Note that \fmtseq{\l}, \fmtseq{\<nnn>} and \fmtseq{\\} are interpreted differently when character-escapes are in effect. See \secref{charescapes}. Escape sequences to include arguments from \arg{Arguments}. Each time a \% escape sequence is found in \arg{Format} the next argument from \arg{Arguments} is formatted according to the specification. \begin{center} \begin{tabular}{|l|p{3.5in}|} \hline \fmtseq{%t} & print/1 the next item (mnemonic: term) \\ \fmtseq{%w} & write/1 the next item \\ \fmtseq{%q} & writeq/1 the next item \\ \fmtseq{%d} & display/1 the next item \\ \fmtseq{%p} & print/1 the next item (identical to \fmtseq{%t}) \\ \fmtseq{%n} & Put the next item as a character (i.e. it is an ASCII value) \\ \fmtseq{%r} & Write the next item N times where N is the second item (an integer) \\ \fmtseq{%s} & Write the next item as a String (so it must be a list of characters) \\ \fmtseq{%f} & Perform a ttyflush/0 (no items used) \\ \fmtseq{%Nc} & Write the next item Centered in $N$ columns. \\ \fmtseq{%Nl} & Write the next item Left justified in $N$ columns. \\ \fmtseq{%Nr} & Write the next item Right justified in $N$ columns. $N$ is a decimal number with at least one digit. The item must be an atom, integer, float or string. \\ \hline \end{tabular} \end{center} \predicate{swritef}{3}{-String, +Format, +Arguments} Equivalent to writef/2, but ``writes'' the result on \arg{String} instead of the current output stream. Example: \begin{code} ?- swritef(S, '%15L%w', ['Hello', 'World']). S = "Hello World" \end{code} \predicate{swritef}{2}{-String, +Format} Equivalent to \exam{swritef(String, Format, []).} \end{description} \subsection{Format} \begin{description} \predicate{format}{1}{+Format} Defined as `\exam{format(Format) :- format(Format, []).}' \predicate{format}{2}{+Format, +Arguments} \arg{Format} is an atom, list of ASCII values, or a Prolog string. \arg{Arguments} provides the arguments required by the format specification. If only one argument is required and this is not a list of ASCII values the argument need not be put in a list. Otherwise the arguments are put in a list. Special sequences start with the tilde (\chr{~}), followed by an optional numeric argument, followed by a character describing the action to be undertaken. A numeric argument is either a sequence of digits, representing a positive decimal number, a sequence \exam{`<character>}, representing the ASCII value of the character (only useful for \fmtseq{~t}) or a asterisk (\chr{*}), in when the numeric argument is taken from the next argument of the argument list, which should be a positive integer. Actions are: \begin{itemize} \fmtchar{~} Output the tilde itself. \fmtchar{a} Output the next argument, which should be an atom. This option is equivalent to {\bf w}. Compatibility reasons only. \fmtchar{c} Output the next argument as an ASCII value. This argument should be an integer in the range [0, \ldots, 255] (including 0 and 255). \fmtchar{d} Output next argument as a decimal number. It should be an integer. If a numeric argument is specified a dot is inserted \arg{argument} positions from the right (useful for doing fixed point arithmetic with integers, such as handling amounts of money). \fmtchar{D} Same as {\bf d}, but makes large values easier to read by inserting a comma every three digits left to the dot or right. \fmtchar{e} Output next argument as a floating point number in exponential notation. The numeric argument specifies the precision. Default is 6 digits. Exact representation depends on the C library function printf(). This function is invoked with the format \mbox{\tt\%.<precision>e}. \fmtchar{E} Equivalent to {\bf e}, but outputs a capital E to indicate the exponent. \fmtchar{f} Floating point in non-exponential notation. See C library function printf(). \fmtchar{g} Floating point in {\bf e} or {\bf f} notation, whichever is shorter. \fmtchar{G} Floating point in {\bf E} or {\bf f} notation, whichever is shorter. \fmtchar{i} Ignore next argument of the argument list. Produces no output. \fmtchar{k} Give the next argument to displayq/1 (canonical write). \fmtchar{n} Output a newline character. \fmtchar{N} Only output a newline if the last character output on this stream was not a newline. Not properly implemented yet. \fmtchar{p} Give the next argument to print/1. \fmtchar{q} Give the next argument to writeq/1. \fmtchar{r} Print integer in radix the numeric argument notation. Thus \fmtseq{~16r} prints its argument hexadecimal. The argument should be in the range $[2, \ldots, 36]$. Lower case letters are used for digits above 9. \fmtchar{R} Same as {\bf r}, but uses upper case letters for digits above 9. \fmtchar{s} Output a string of ASCII characters or a string (see string/1 and \secref{strings}) from the next argument. \fmtchar{t} All remaining space between 2 tabs tops is distributed equally over \fmtseq{~t} statements between the tabs tops. This space is padded with spaces by default. If an argument is supplied this is taken to be the ASCII value of the character used for padding. This can be used to do left or right alignment, centering, distributing, etc. See also \fmtseq{~|} and \fmtseq{~+} to set tab stops. A tabs top is assumed at the start of each line. \fmtchar{|} Set a tabs top on the current position. If an argument is supplied set a tabs top on the position of that argument. This will cause all \fmtseq{~t}'s to be distributed between the previous and this tabs \fmtchar{+} Set a tabs top relative to the current position. Further the same as \fmtseq{~|}. \fmtchar{w} Give the next argument to write/1. \end{itemize} Example: \begin{code} simple_statistics :- <obtain statistics> % left to the user format('~tStatistics~t~72|~n~n'), format('Runtime: ~`.t ~2f~34| Inferences: ~`.t ~D~72|~n', [RunT, Inf]), .... \end{code} Will output \begin{code} Statistics Runtime: .................. 3.45 Inferences: .......... 60,345 \end{code} \predicate{format}{3}{+Stream, +Format, +Arguments} As format/2, but write the output on the given \arg{Stream}. \predicate{sformat}{3}{-String, +Format, +Arguments} Equivalent to format/2, but ``writes'' the result on \arg{String} instead of the current output stream. Example: \begin{code} ?- sformat(S, '~w~t~15|~w', ['Hello', 'World']). S = "Hello World" \end{code} \predicate{sformat}{2}{-String, +Format} Equivalent to `\exam{sformat(String, Format, []).}' \end{description} \subsection{Programming Format} \begin{description} \predicate{format_predicate}{2}{+Char, +Head} If a sequence \fmtseq{~c} (tilde, followed by some character) is found, the format derivatives will first check whether the user has defined a predicate to handle the format. If not, the built in formatting rules described above are used. \arg{Char} is either an {\sc ascii} value, or a one character atom, specifying the letter to be (re)defined. \arg{Head} is a term, whose name and arity are used to determine the predicate to call for the redefined formatting character. The first argument to the predicate is the numeric argument of the format command, or the atom \const{default} if no argument is specified. The remaining arguments are filled from the argument list. The example below redefines \fmtseq{~n} to produce \arg{Arg} times return followed by linefeed (so a (Grr.) DOS machine is happy with the output). \begin{code} :- format_predicate(n, dos_newline(_Arg)). dos_newline(Arg) :- between(1, Ar, _), put(13), put(10), fail ; true. \end{code} \end{description} \section{Terminal Control} The following predicates form a simple access mechanism to the Unix termcap library to provide terminal independent I/O for screen terminals. The library package \file{library(tty)} builds on top of these predicates. \begin{description} \predicate{tty_get_capability}{3}{+Name, +Type, -Result} Get the capability named \arg{Name} from the termcap library. See termcap(5) for the capability names. \arg{Type} specifies the type of the expected result, and is one of \const{string}, \const{number} or \const{bool}. String results are returned as an atom, number result as an integer and bool results as the atom \const{on} or \const{off}. If an option cannot be found this predicate fails silently. The results are only computed once. Successive queries on the same capability are fast. \predicate{tty_goto}{2}{+X, +Y} Goto position \mbox{(\arg{X}, \arg{Y})} on the screen. Note that the predicates line_count/2 and line_position/2 will not have a well defined behaviour while using this predicate. \predicate{tty_put}{2}{+Atom, +Lines} Put an atom via the termcap library function tputs(). This function decodes padding information in the strings returned by tty_get_capability/3 and should be used to output these strings. \arg{Lines} is the number of lines affected by the operation, or 1 if not applicable (as in almost all cases). \predicate{set_tty}{2}{-OldStream, +NewStream} Set the output stream, used by tty_put/2 and tty_goto/2 to a specific stream. Default is user_output. \end{description} \section{Operating System Interaction} \begin{description} \predicate{shell}{2}{+Command, -Status} Execute \arg{Command} on the operating system. \arg{Command} is given to the Bourne shell (/bin/sh). \arg{Status} is unified with the exit status of the command. On \arg{Win32} systems, shell/[1,2] executes the command using the CreateProcess() API and waits for the command to terminate. If the command ends with a \chr{\&} sign, the command is handed to the WinExec() API, which does not wait for the new task to terminate. See also win_exec/2. \predicate{shell}{1}{+Command} Equivalent to `\exam{shell(Command, 0)}'. \predicate{shell}{0}{} Start an interactive Unix shell. Default is \file{/bin/sh}, the environment variable \env{SHELL} overrides this default. Not available for Win32 platforms. \predicate{win_exec}{2}{+Command, +Show} Win32 systems only. Spawns a Windows task without waiting for its completion. \arg{Show} is either \const{iconic} or \const{normal} and dictates the initial status of the window. The \const{iconic} option is notably handy to start (DDE) servers. \predicate{getenv}{2}{+Name, -Value} Get Unix environment variable (see csh(1) and sh(1)). Fails if the variable does not exist. \predicate{setenv}{2}{+Name, +Value} Set Unix environment variable. \arg{Name} and \arg{Value} should be instantiated to atoms or integers. The environment variable will be passed to shell/[0-2] and can be requested using getenv/2. \predicate{unsetenv}{1}{+Name} Remove Unix environment variable from the environment. \predicate{get_time}{1}{-Time} Return the number of seconds that elapsed since the epoch of Unix, 1 January 1970, 0 hours. \arg{Time} is a floating point number. Its granularity is system dependent. On {\sc sun}, this is 1/60 of a second. \predicate{convert_time}{8}{+Time, -Year, -Month, -Day, -Hour, -Minute, -Second, -MilliSeconds} Convert a time stamp, provided by get_time/1, time_file/2, etc. \arg{Year} is unified with the year, \arg{Month} with the month number (January is 1), \arg{Day} with the day of the month (starting with 1), \arg{Hour} with the hour of the day (0--23), \arg{Minute} with the minute (0--59). \arg{Second} with the second (0--59) and \arg{MilliSecond} with the milliseconds (0--999). Note that the latter might not be accurate or might always be 0, depending on the timing capabilities of the system. \end{description} \section{File System Interaction} \begin{description} \predicate{access_file}{2}{+File, +Mode} Succeeds if \arg{File} exists and can be accessed by this prolog process under mode \arg{Mode}. \arg{Mode} is one of the atoms \const{read}, \const{write}, \const{append}, \const{exist}, \const{none} or \const{execute}. \arg{File} may also be the name of a directory. Fails silently otherwise. \exam{access_file(File, none)} simply succeeds without testing anything. If `Mode' is \const{write} or \const{append}, this predicate also succeeds if the file does not exist and the user has write-access to the directory of the specified location. \predicate{exists_file}{1}{+File} Succeeds when \arg{File} exists. This does not imply the user has read and/or write permission for the file. \predicate{file_directory_name}{2}{+File, -Directory} Extracts the directory-part of \arg{File}. The resulting \arg{Directory} name ends with the directory separator character \chr{/}. If \arg{File} is an atom that does not contain any directory separator characters, the empty atom \const{''} is returned. See also file_base_name/2. \predicate{file_base_name}{2}{+File, -BaseName} Extracts the filename part from a path specification. If \arg{File} does not contain any directory separators, \arg{File} is returned. \predicate{same_file}{2}{+File1, +File2} Succeeds if both filenames refer to the same physical file. That is, if \arg{File1} and \arg{File2} are the same string or both names exist and point to the same file (due to hard or symbolic links and/or relative vs. absolute paths). \predicate{exists_directory}{1}{+Directory} Succeeds if \arg{Directory} exists. This does not imply the user has read, search and or write permission for the directory. \predicate{delete_file}{1}{+File} Unlink \arg{File} from the Unix file system. \predicate{rename_file}{2}{+File1, +File2} Rename \arg{File1} into \arg{File2}. Currently files cannot be moved across devices. \predicate{size_file}{2}{+File, -Size} Unify \arg{Size} with the size of \arg{File} in characters. \predicate{time_file}{2}{+File, -Time} Unify the last modification time of \arg{File} with \arg{Time}. \arg{Time} is a floating point number expressing the seconds elapsed since Jan~1, 1970. \predicate{absolute_file_name}{2}{+File, -Absolute} Expand Unix file specification into an absolute path. User home directory expansion (\file{~} and \file{~<user>}) and variable expansion is done. The absolute path is canonised: references to \file{.} and \file{..} are deleted. SWI-Prolog uses absolute file names to register source files independent of the current working directory. See also absolute_file_name/3. \predicate{absolute_file_name}{3}{+Spec, +Options, -Absolute} Converts the given file specification into an absolute path. \arg{Option} is a list of options to guide the conformation process: \begin{description} \termitem{extensions}{ListOfExtensions} List of file-extensions to try. Default is \const{''}. For each extension, absolute_file_name/3 will first add the extension and then verify the conditions imposed by the other options. If the condition fails, the next extension of the list is tried. Extensions may be specified both as \fileext{.ext} or plain \const{ext}. \termitem{access}{Mode} Imposes the condition access_file(\arg{File}, \arg{Mode}). \arg{Mode} is on of \const{read}, \const{write}, \const{append}, \const{exist} or \const{none}. See also access_file/2. \termitem{file_type}{Type} Defines extensions. Current mapping: \const{txt} implies \const{['']}, \const{prolog} implies \const{['.pl', '']}, \const{executable} implies \const{['.so', '']}, \const{qlf} implies \const{['.qlf', '']} and \const{directory} implies \const{['']}. \termitem{file_errors}{fail/true} Report if the path cannot be resolved or be silent. The default is to stay silent. \termitem{solutions}{first/all} If \const{first} (default), the predicates leaves no choice-point. Otherwise a choice-point will be left and backtracking may yield more solutions. \end{description} \predicate{is_absolute_file_name}{1}{+File} True if \arg{File} specifies and absolute path-name. On Unix systems, this implies the path starts with a `/'. For Microsoft based systems this implies the path starts with \file{<letter>:}. This predicate is intended to provide platform-independent checking for absolute paths. See also absolute_file_name/2 and prolog_to_os_filename/2. \predicate{file_name_extension}{3}{?Base, ?Extension, ?Name} This predicate is used to add, remove or test filename extensions. The main reason for its introduction is to deal with different filename properties in a portable manner. If the file system is case-insensitive, testing for an extension will be done case-insensitive too. \arg{Extension} may be specified with or without a leading dot (\chr{.}). If an \arg{Extension} is generated, it will not have a leading dot. \predicate{expand_file_name}{2}{+WildCard, -List} Unify \arg{List} with a sorted list of files or directories matching \arg{WildCard}. The normal Unix wildcard constructs `\const{?}', `\const{*}', `\const{[\ldots]}' and `\const{\{\ldots\}}' are recognised. The interpretation of `\const{\{\ldots\}}' is interpreted slightly different from the C shell (csh(1)). The comma separated argument can be arbitrary patterns, including `\const{\{\ldots\}}' patterns. The empty pattern is legal as well: `\file{\{.pl,\}}' matches either `\file{.pl}' or the empty string. \predicate{prolog_to_os_filename}{2}{?PrologPath, ?OsPath} Converts between the internal Prolog pathname conventions and the operating-system pathname conventions. The internal conventions are Unix and this predicates is equivalent to =/2 (unify) on Unix systems. On DOS systems it will change the directory-separator, limit the filename length map dots, except for the last one, onto underscores. \predicate{read_link}{3}{+File, -Link, -Target} If \arg{File} points to a symbolic link, unify \arg{Link} with the value of the link and \arg{Target} to the file the link is pointing to. \arg{Target} points to a file, directory or non-existing entry in the file system, but never to a link. Fails if \arg{File} is not a link. Fails always on systems that do not support symbolic links. \predicate{tmp_file}{2}{+Base, -TmpName} Create a name for a temporary file. \arg{Base} is an identifier for the category of file. The \arg{TmpName} is guaranteed to be unique. If the system halts, it will automatically remove all created temporary files. \predicate{chdir}{1}{+Path} Change working directory to \arg{Path}.% \bug{Some of the file-I/O predicates use local filenames. Using chdir/1 while file-bound streams are open causes wrong results on telling/1, seeing/1 and current_stream/3} \end{description} \section{User Toplevel Manipulation} \begin{description} \predicate{break}{0}{} Recursively start a new Prolog top level. This Prolog top level has its own stacks, but shares the heap with all break environments and the top level. Debugging is switched off on entering a break and restored on leaving one. The break environment is terminated by typing the system's \mbox{end-of-file} character (control-D). If the \argoption{-t}{toplevel} command line option is given this goal is started instead of entering the default interactive top level (prolog/0). \predicate{abort}{0}{} Abort the Prolog execution and start a new top level. If the \argoption{-t}{toplevel} command line options is given this goal is started instead of entering the default interactive top level. Break environments are aborted as well. All open files except for the terminal related files are closed. The input- and output stream again refers to \arg{user}.% \bug{Erased clauses which could not actually be removed from the database, because they are active in the interpreter, will never be garbage collected after an abort.} \predicate{halt}{0}{} Terminate Prolog execution. Open files are closed and if the command line option \cmdlineoption{-tty} is not active the terminal status (see Unix stty(1)) is restored. Hooks may be registered both in Prolog and in foreign code. Prolog hooks are registered using at_halt/1. halt/0 is equivalent to \exam{halt(0)}. \predicate{halt}{1}{+Status} Terminate Prolog execution with given status. Status is an integer. See also halt/0. \predicate{prolog}{0}{} This goal starts the default interactive top level. Queries are read from the stream \const{user_input}. See also the \const{history} feature (feature/2). The prolog/0 predicate is terminated (succeeds) by typing the end-of-file character (Unix: control-D). \end{description} The following two hooks allow for expanding queries and handling the result of a query. These hooks are used by the toplevel variable expansion mechanism described in \secref{topvars}. \begin{description} \predicate{expand_query}{4}{+Query, -Expanded, +Bindings, -ExpandedBindings} Hook in module \const{user}, normally not defined. \arg{Query} and \arg{Bindings} represents the query read from the user and the names of the free variables as obtained using read_term/3. If this predicate succeeds, it should bind \arg{Expanded} and \arg{ExpandedBindings} to the query and bindings to be executed by the toplevel. This predicate is used by the toplevel (prolog/0). See also expand_answer/2 and term_expansion/2. \predicate{expand_answer}{2}{+Bindings, -ExpandedBindings} Hook in module \const{user}, normally not defined. Expand the result of a successfully executed toplevel query. \arg{Bindings} is the query $<Name>=<Value>$ binding list from the query. \arg{ExpandedBindings} must be unified with the bindings the toplevel should print. \end{description} \section{Creating a Protocol of the User Interaction} SWI-Prolog offers the possibility to log the interaction with the user on a file.% \footnote{A similar facility was added to Edinburgh C-Prolog by Wouter Jansweijer.} All Prolog interaction, including warnings and tracer output, are written on the protocol file. \begin{description} \predicate{protocol}{1}{+File} Start protocolling on file \arg{File}. If there is already a protocol file open then close it first. If \arg{File} exists it is truncated. \predicate{protocola}{1}{+File} Equivalent to protocol/1, but does not truncate the \arg{File} if it exists. \predicate{noprotocol}{0}{} Stop making a protocol of the user interaction. Pending output is flushed on the file. \predicate{protocolling}{1}{-File} Succeeds if a protocol was started with protocol/1 or protocola/1 and unifies \arg{File} with the current protocol output file. \end{description} \section{Debugging and Tracing Programs} \label{sec:debugger} \begin{description} \predicate{trace}{0}{} Start the tracer. trace/0 itself cannot be seen in the tracer. Note that the Prolog toplevel treats trace/0 special; it means `trace the next goal'. \predicate{tracing}{0}{} Succeeds when the tracer is currently switched on. tracing/0 itself can not be seen in the tracer. \predicate{notrace}{0}{} Stop the tracer. notrace/0 itself cannot be seen in the tracer. \predicate{trace}{1}{+Pred} Equivalent to \exam{trace(\arg{Pred}, +all)}. \predicate{trace}{2}{+Pred, +Ports} Put a trace-point on all predicates satisfying the predicate specification \arg{Pred}. \arg{Ports} is a list of portnames (\const{call}, \const{redo}, \const{exit}, \const{fail}). The atom \const{all} refers to all ports. If the port is preceded by a \const{-} sign the trace-point is cleared for the port. If it is preceded by a \const{+} the trace-point is set. The predicate trace/2 activates debug mode (see debug/0). Each time a port (of the 4-port model) is passed that has a trace-point set the goal is printed as with trace/0. Unlike trace/0 however, the execution is continued without asking for further information. Examples: \begin{center} \begin{tabular}{lp{3in}} \exam{?- trace(hello).} & Trace all ports of hello with any arity in any module. \\ \exam{?- trace({foo}/2, +fail).} & Trace failures of {foo}/2 in any module. \\ \exam{?- trace({bar}/1, -all).} & Stop tracing {bar}/1. \end{tabular} \end{center} The predicate debugging/0 shows all currently defined trace-points. \predicate{notrace}{1}{+Goal} Call \arg{Goal}, but suspend the debugger while \arg{Goal} is executing. The current implementation cuts the choicepoints of \arg{Goal} after successful completion. See once/1. Later implementations may have the same semantics as call/1. \predicate{debug}{0}{} Start debugger (stop at spy points). \predicate{nodebug}{0}{} Stop debugger (do not trace, nor stop at spy points). \predicate{debugging}{0}{} Print debug status and spy points on current output stream. \predicate{spy}{1}{+Pred} Put a spy point on all predicates meeting the predicate specification \arg{Pred}. See \secref{listing}. \predicate{nospy}{1}{+Pred} Remove spy point from all predicates meeting the predicate specification \arg{Pred}. \predicate{nospyall}{0}{} Remove all spy points from the entire program. \predicate{leash}{1}{?Ports} Set/query leashing (ports which allow for user interaction). \arg{Ports} is one of \arg{+Name}, \arg{-Name}, \arg{?Name} or a list of these. \arg{+Name} enables leashing on that port, \arg{-Name} disables it and \arg{?Name} succeeds or fails according to the current setting. Recognised ports are: \const{call}, \const{redo}, \const{exit}, \const{fail} and \const{unify}. The special shorthand \const{all} refers to all ports, \const{full} refers to all ports except for the unify port (default). \const{half} refers to the \const{call}, \const{redo} and \const{fail} port. \predicate{visible}{1}{+Ports} Set the ports shown by the debugger. See leash/1 for a description of the port specification. Default is \const{full}. \predicate{unknown}{2}{-Old, +New} Unify \arg{Old} with the current value of the unknown system flag. On success \arg{New} will be used to specify the new value. \arg{New} should be instantiated to either \const{fail} or \const{trace} and determines the interpreters action when an undefined predicate which is not declared dynamic is encountered (see dynamic/1). \const{fail} implies the predicate just fails silently. \const{trace} implies the tracer is started. Default is \const{trace}. The unknown flag is local to each module and unknown/2 is module transparent. Using it as a directive in a module file will only change the unknown flag for that module. Using the :/2 construct the behaviour on trapping an undefined predicate can be changed for any module. Note that if the unknown flag for a module equals \const {fail} the system will not call exception/3 and will {\bf not} try to resolve the predicate via the dynamic library system. The system will still try to import the predicate from the public module. \predicate{style_check}{1}{+Spec} Set style checking options. \arg{Spec} is either \mbox{\tt +<option>}, \mbox{\tt -<option>}, \mbox{\tt ?<option>} or a list of such options. \mbox{\tt +<option>} sets a style checking option, \mbox{\tt -<option>} clears it and \mbox{\tt ?<option>} succeeds or fails according to the current setting. consult/1 and derivatives resets the style checking options to their value before loading the file. If---for example---a file containing long atoms should be loaded the user can start the file with: \begin{code} :- style_check(-atom). \end{code} Currently available options are: \begin{center} \begin{tabular}{|l|c|p{3.5in}|} \hline Name & Default & Description \\ \hline \const{singleton} & on & read_clause/1 (used by consult/1) warns on variables only appearing once in a term (clause) which have a name not starting with an underscore. \\ \const{atom} & on & read/1 and derivatives will produce an error message on quoted atoms or strings longer than 5 lines. \\ \const{dollar} & off & Accept dollar as a lower case character, thus avoiding the need for quoting atoms with dollar signs. System maintenance use only. \\ \const{discontiguous} & on & Warn if the clauses for a predicate are not together in the same source file. \\ \const{string} & off & Read and derivatives transform \const{"\ldots"} into a prolog string instead of a list of ASCII characters. \\ \hline \end{tabular} \end{center} \end{description} \section{Obtaining Runtime Statistics} \begin{description} \predicate{statistics}{2}{+Key, -Value} Unify system statistics determined by \arg{Key} with \arg{Value}. The possible keys are given in the \tabref{statistics}. \begin{table} \begin{center} \begin{tabular}{|l|p{4in}|} \hline cputime & (User) {\sc cpu} time since Prolog was started in seconds \\ inferences & Total number of passes via the call and redo ports since Prolog was started. \\ heap & Estimated total size of the heap (see \secref{heap}) \\ heapused & Bytes heap in use by Prolog. \\ heaplimit & Maximum size of the heap (see \secref{heap}) \\ local & Allocated size of the local stack in bytes. \\ localused & Number of bytes in use on the local stack. \\ locallimit & Size to which the local stack is allowed to grow \\ global & Allocated size of the global stack in bytes. \\ globalused & Number of bytes in use on the global stack. \\ globallimit & Size to which the global stack is allowed to grow \\ trail & Allocated size of the trail stack in bytes. \\ trailused & Number of bytes in use on the trail stack. \\ traillimit & Size to which the trail stack is allowed to grow \\ atoms & Total number of defined atoms. \\ functors & Total number of defined name/arity pairs. \\ predicates & Total number of predicate definitions. \\ modules & Total number of module definitions. \\ codes & Total amount of byte codes in all clauses. \\ \hline \end{tabular} \end{center} \caption{Keys for statistics/2} \label{tab:statistics} \end{table} \predicate{statistics}{0}{} Display a table of system statistics on the current output stream. \predicate{time}{1}{+Goal} Execute \arg{Goal} just like once/1 (i.e. leaving no choice points), but print used time, number of logical inferences and the average number of \arg{lips} (logical inferences per second). Note that SWI-Prolog counts the actual executed number of inferences rather than the number of passes through the call- and redo ports of the theoretical 4-port model. \end{description} \section{Finding Performance Bottlenecks} SWI-Prolog offers a statistical program profiler similar to Unix prof(1) for C and some other languages. A profiler is used as an aid to find performance pigs in programs. It provides information on the time spent in the various Prolog predicates. The profiler is based on the assumption that if we monitor the functions on the execution stack on time intervals not correlated to the program's execution the number of times we find a procedure on the environment stack is a measure of the time spent in this procedure. It is implemented by calling a procedure each time slice Prolog is active. This procedure scans the local stack and either just counts the procedure on top of this stack (\const{plain} profiling) or all procedures on the stack (\const{cumulative} profiling). To get accurate results each procedure one is interested in should have a reasonable number of counts. Typically a minute runtime will suffice to get a rough overview of the most expensive procedures. \begin{description} \predicate{profile}{3}{+Goal, +Style, +Number} Execute \arg{Goal} just like time/1. Collect profiling statistics according to style (see profiler/2) and show the top \arg{Number} procedures on the current output stream (see show_profile/1). The results are kept in the database until reset_profiler/0 or profile/3 is called and can be displayed again with show_profile/1. profile/3 is the normal way to invoke the profiler. The predicates below are low-level predicates that can be used for special cases. \predicate{show_profile}{1}{+Number} Show the collected results of the profiler. Stops the profiler first to avoid interference from show_profile/1. It shows the top \arg{Number} predicates according the percentage {\sc cpu}-time used.% \footnote{show_profile/1 is defined in Prolog and takes a considerable amount of memory.} \predicate{profiler}{2}{-Old, +New} Query or change the status of the profiler. The status is one of \const{off}, \const{plain} or \const{cumulative}. \const{plain} implies the time used by children of a predicate is not added to the time of the predicate. For status \const{cumulative} the time of children is added (except for recursive calls). Cumulative profiling implies the stack is scanned up to the top on each time slice to find all active predicates. This implies the overhead grows with the number of active frames on the stack. Cumulative profiling starts debugging mode to disable tail recursion optimisation, which would otherwise remove the necessary parent environments. Switching status from \const{plain} to \const{cumulative} resets the profiler. Switching to and from status \const{off} does not reset the collected statistics, thus allowing to suspend profiling for certain parts of the program. \predicate{reset_profiler}{0}{} Switches the profiler to \const{off} and clears all collected statistics. \predicate{profile_count}{3}{+Head, -Calls, -Promilage} Obtain profile statistics of the predicate specified by \arg{Head}. \arg{Head} is an atom for predicates with arity 0 or a term with the same name and arity as the predicate required (see current_predicate/2). \arg{Calls} is unified with the number of `calls' and `redos' while the profiler was active. \arg{Promilage} is unified with the relative number of counts the predicate was active (\const{cumulative}) or on top of the stack (\const{plain}). \arg{Promilage} is an integer between 0 and 1000. \end{description} \section{Memory Management} Note: limit_stack/2 and trim_stacks/0 have no effect on machines that do not offer dynamic stack expansion. On these machines these predicates simply succeed to improve portability. \begin{description} \predicate{garbage_collect}{0}{} Invoke the global- and trail stack garbage collector. Normally the garbage collector is invoked automatically if necessary. Explicit invocation might be useful to reduce the need for garbage collections in time critical segments of the code. After the garbage collection trim_stacks/0 is invoked to release the collected memory resources. \predicate{limit_stack}{2}{+Key, +Kbytes} Limit one of the stack areas to the specified value. \arg{Key} is one of \const{local}, \const{global} or \const{trail}. The limit is an integer, expressing the desired stack limit in K bytes. If the desired limit is smaller than the currently used value, the limit is set to the nearest legal value above the currently used value. If the desired value is larger than the maximum, the maximum is taken. Finally, if the desired value is either 0 or the atom \const{unlimited} the limit is set to its maximum. The maximum and initial limit is determined by the command line options \cmdlineoption{-L}, \cmdlineoption{-G} and \cmdlineoption{-T}. \predicate{trim_stacks}{0}{} Release stack memory resources that are not in use at this moment, returning them to the operating system. Trim stack is a relatively cheap call. It can be used to release memory resources in a backtracking loop, where the iterations require typically seconds of execution time and very different, potentially large, amounts of stack space. Such a loop should be written as follows: \begin{code} loop :- generator, trim_stacks, potentially_expensive_operation, stop_condition, !. \end{code} The prolog top level loop is written this way, reclaiming memory resources after every user query. \predicate{stack_parameter}{4}{+Stack, +Key, -Old, +New} Query/set a parameter for the runtime stacks. \arg{Stack} is one of \const{local}, \const{global}, \const{trail} or \const{argument}. The table below describes the \arg{Key}/\arg{Value} pairs. Old is first unified with the current value. \begin{center} \begin{tabular}{|l|l|} \hline \const{limit} & Maximum size of the stack in bytes \\ \const{min_free} & Minimum free space at entry of foreign predicate \\ \hline \end{tabular} \end{center} This predicate is currently only available on versions that use the stack-shifter to enlarge the runtime stacks when necessary. It's definition is subject to change. \end{description} \section{Windows DDE interface} \label{sec:DDE} The predicates in this section deal with MS-Windows `Dynamic Data Exchange' or DDE protocol.% \footnote{This interface is contributed by Don Dwiggins.} A Windows DDE conversation is a form of interprocess communication based on sending reserved window-events between the communicating processes. See also \secref{DLL} for loading Windows DLL's into SWI-Prolog. \subsection{DDE client interface} The DDE client interface allows Prolog to talk to DDE server programs. We will demonstrate the use of the DDE interface using the Windows PROGMAN (Program Manager) application: \begin{code} 1 ?- open_dde_conversation(progman, progman, C). C = 0 2 ?- dde_request(0, groups, X) --> Unifies X with description of groups 3 ?- dde_execute(0, '[CreateGroup("DDE Demo")]'). 4 ?- close_dde_conversation(0). \end{code} For details on interacting with \program{progman}, use the SDK online manual section on the Shell DDE interface. See also the Prolog \file{library(progman)}, which may be used to write simple Windows setup scripts in Prolog. \begin{description} \predicate{open_dde_conversation}{3}{+Service, +Topic, -Handle} Open a conversation with a server supporting the given service name and topic (atoms). If successful, \arg{Handle} may be used to send transactions to the server. If no willing server is found this predicate fails silently. \predicate{close_dde_conversation}{1}{+Handle} Close the conversation associated with \arg{Handle}. All opened conversations should be closed when they're no longer needed, although the system will close any that remain open on process termination. \predicate{dde_request}{3}{+Handle, +Item, -Value} Request a value from the server. \arg{Item} is an atom that identifies the requested data, and \arg{Value} will be a string (\const{CF_TEXT} data in DDE parlance) representing that data, if the request is successful. If unsuccessful, \arg{Value} will be unified with a term of form \mbox{\tt error(<Reason>)}, identifying the problem. This call uses SWI-Prolog string objects to return the value rather then atoms to reduce the load on the atom-space. See \secref{strings} for a discussion on this data type. \predicate{dde_execute}{2}{+Handle, +Command} Request the DDE server to execute the given command-string. Succeeds if the command could be executed and fails with error message otherwise. \predicate{dde_poke}{4}{+Handle, +Item, +Command} Issue a \const{POKE} command to the server on the specified \arg{Item}. Command is passed as data of type \const{CF_TEXT}. \end{description} \subsection{DDE server mode} The (autoload) \file{library(dde)} defines primitives to realise simple DDE server applications in SWI-Prolog. These features are provided as of version 2.0.6 and should be regarded prototypes. The C-part of the DDE server can handle some more primitives, so if you need features not provided by this interface, please study \file{library(dde)}. \begin{description} \predicate{dde_register_service}{2}{+Template, +Goal} Register a server to handle DDE request or DDE execute requests from other applications. To register a service for a DDE request, \arg{Template} is of the form: \begin{quote} +Service(+Topic, +Item, +Value) \end{quote} \arg{Service} is the name of the DDE service provided (like \program{progman} in the client example above). \arg{Topic} is either an atom, indicating \arg{Goal} only handles requests on this topic or a variable that also appears in \arg{Goal}. \arg{Item} and \arg{Value} are variables that also appear in \arg{Goal}. The example below registers the Prolog feature/2 predicate to be accessible from other applications. The request may be given from the same Prolog as well as from another application. \begin{code} ?- dde_register_service(prolog(feature, F, V), feature(F, V)). ?- open_dde_conversation(prolog, feature, Handle), dde_request(Handle, home, Home), close_dde_conversation(Handle). Home = '/usr/local/lib/pl-2.0.6/' \end{code} Handling DDE \const{execute} requests is very similar. In this case the template is of the form: \begin{quote} +Service(+Topic, +Item) \end{quote} Passing a \arg{Value} argument is not needed as execute requests either succeed or fail. If \arg{Goal} fails, a `not processed' is passed back to the caller of the DDE request. \predicate{dde_unregister_service}{1}{+Service} Stop responding to \arg{Service}. If Prolog is halted, it will automatically call this on all open services. \predicate{dde_current_service}{2}{-Service, -Topic} Find currently registered services and the topics served on them. \predicate{dde_current_connection}{2}{-Service, -Topic} Find currently open conversations. \end{description} \section{Miscellaneous} \begin{description} \predicate{dwim_match}{2}{+Atom1, +Atom2} Succeeds if \arg{Atom1} matches \arg{Atom2} in `Do What I Mean' sense. Both \arg{Atom1} and \arg{Atom2} may also be integers or floats. The two atoms match if: \begin{shortlist} \item They are identical \item They differ by one character (spy $\equiv$ spu) \item One character is inserted/deleted (debug $\equiv$ deug) \item Two characters are transposed (trace $\equiv$ tarce) \item `Sub-words' are glued differently (existsfile $\equiv$ existsFile $\equiv$ exists_file) \item Two adjacent sub words are transposed (existsFile $\equiv$ fileExists) \end{shortlist} \predicate{dwim_match}{3}{+Atom1, +Atom2, -Difference} Equivalent to dwim_match/2, but unifies \arg{Difference} with an atom identifying the the difference between \arg{Atom1} and \arg{Atom2}. The return values are (in the same order as above): \const{equal}, \const{mismatched_char}, \const{inserted_char}, \const{transposed_char}, \const{separated} and \const{transposed_word}. \predicate{wildcard_match}{2}{+Pattern, +String} Succeeds if \arg{String} matches the wildcard pattern \arg{Pattern}. \arg{Pattern} is very similar the the Unix csh pattern matcher. The patterns are given below: \begin{center}\begin{tabular}{ll} \const{?} & Matches one arbitrary character. \\ \const{*} & Matches any number of arbitrary characters. \\ \const{[\ldots]} & Matches one of the characters specified between the brackets. \mbox{\tt <char1>-<char2>} indicates a range. \\ \const{\{\ldots\}} & Matches any of the patterns of the comma separated list between the braces. \end{tabular}\end{center} Example: \begin{code} ?- wildcard_match('[a-z]*.{pro,pl}[%~]', 'a_hello.pl%'). \end{code} \predicate{gensym}{2}{+Base, -Unique} Generate a unique atom from base \arg{Base} and unify it with \arg{Unique}. \arg{Base} should be an atom. The first call will return \mbox{<base>1}, the next \mbox{<base>2}, etc. Note that this is no warrant that the atom is unique in the system.% \bug{I plan to supply a real gensym/2 which does give this warrant for future versions.} \predicate{sleep}{1}{+Time} Suspend execution \arg{Time} seconds. \arg{Time} is either a floating point number or an integer. Granularity is dependent on the system's timer granularity. A negative time causes the timer to return immediately. On most non-realtime operating systems we can only ensure execution is suspended for {\bf at least} \arg{Time} seconds. \end{description} 
(.txt)